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INTRODUCTION 


Programming RSX-11M in MACRO is intended _ for MACRO-11 
programmers who use _ services of the RSX-11M operating system 
beyond those provided by the MACRO-11 programming language itself. 
This course describes the various services and how to use them 
from a task which you write. 


This course is self-paced, which means that you learn at 
whatever rate is comfortable for you. 


Instead of a teacher, you have a course administrator and a 
subject matter expert. In Some cases, the same person can perform 
both functions. The course administrator manages the mechanics of 
the course and makes sure you have easy access to the system and 
the on-line course materials. As you finish modules, s/he records 
your progress. The subject matter expert helps you if you have a 
technical question. Before you consult the expert, however, read 
the course materials and references in an effort to answer the 
question yourself. 


This Student Guide covers the following topics: 


Course prerequisites 

Course goals (and Nongoals) 
Course organization 

Course map description 
Course resources 

How to take the course 
Personal Progress Plotter 
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PREREQUISITES 


To be prepared for this course, you must have taken the 
following DIGITAL courses, or you must have equivalent experience. 


1. RSX-11M Utilities and Commands. Specifically, you must be 
able to logon/logoff, edit files, and develop/run/debug 
programs under RSX-11M. 


2. Programming in MACRO-1l. 


COURSE GOALS AND NONGOALS 


On completion of this course, you should be able to write 
tasks which: 


1. Use executive directives 

2. Perform intertask communication and coordination 

3. Perform synchronous and asynchronous I/0 operations 
4. Use overlays 


5. Use memory management facilities to communicate between 
tasks and make more effective use of available memory 


6. Use File Control Services to create and maintain files. 
This course does not teach the following: 


1. The PDP-11 instruction set and the MACRO-11 programming 
language 


2. The Digital Command Language (DCL) or Monitor Console 
Routine (MCR) 


3. The program development cycle. 
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COURSE ORGANIZATION 


This course is self-paced for independent study. The course 
material is structured in modules. Each module is a lesson on one 
or more skills required to fulfill the course goals. A module 
consists of: 


e An introduction to the subject matter of the module 


e A list of objectives, which describe what you_ should 
achieve by studying the.module 


e A list of resources that provide reference materials and 
additional reading for the module 


e The module text, including explanatory text, figures, 
tables, examples, and references to readings in the 
manuals j 


e Learning activities (for some modules), consisting of 
reading assignments or written exercises which are 
essential to your learning the material 


e Written and/or lab tests and exercises (bound |. separately) 
which you can use to measure your achievement. Solutions 
are provided for all exercises. 


The course is bound in two’ volumes. The first volume 
contains this student guide, the 19 modules (except for their 
tests/exercises), the appendices, and a glossary. The second 


volume contains the tests/exercises for each module. 


COURSE MAP DESCRIPTION 


The course map shows how each module relates to the other 
modules and to the course as a whole. Before beginning a specific 
module, it is recommended that you first complete all modules with 
arrows leading into that module. These prerequisite modules 
present material necessary to understanding the module you are 
about to study. 


If you have no preference, study the modules in numerical 
order, 1 through 1@. . 
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COURSE MAP 


DYNAMIC REGIONS 
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USING FILE 


CONTROL SERVICES 


MEMORY 
MANAGEMENT 
CONCEPTS 


USING DIRECTIVES 
FOR INTERTASK 
COMMUNICATION 


USING THE 


Qlo DIRECTIVE 


TK-7749 


STUDENT GUIDE 


COURSE RESOURCES 


Required References 
1. IAS/RSX-11 I/O Operations Manual (AA-M176A-TC) 


2. IAS/RSX-11 System Library Routines Reference Manual 
(AA-5580A-TC) 


3. RSX-11M Mini-Reference (AV-557@0D-TC) 
4. RSX-11M/M-PLUS Executive Reference Manual (AA-L675A-TC) 
5. RSX-11M/M-PLUS I/O Drivers Reference Manual (AA-L677A-TC) 


6. RSX-11M/M-PLUS Task Builder Manual (AA-L68@A-TC) 


Optional References 
1. PDP-11 MACRO-11 Language Reference Manual (AA-58@75B-TC) 


2. PDP-11 Processor Handbook (EB-19492-29/81) 
3% RMS-11 User's Guide (AA-D538A-TC) 


4. RMS-11 MACRO-11 Reference Manual (AA-H683A-TC) 
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HOW TO TAKE THE COURSE 


Because this is a self-paced course, you determine how much 
time to devote to each subject. You can pass quickly over 
familiar topics. You can spend more time on topics which are of 
interest to you, or which you can use often in your job, and less 
time on topics which have little use in your job. 


Each time you are ready to begin a new module, first read the 
introduction and the objectives. If you feel that you already 
understand the material in the module, you can go immediately to 
the tests/exercises for that module. If you don't understand much 
of the material, read the module. If you understand some of the 
concepts but not others, just look over the program examples for 
the concepts you understand. Read the text and study the examples 
for concepts you don't understand. The text explains new concepts 
and refers you to related readings in the manuals. The program 
examples provide working examples which show you how to apply the 
concepts. 


Some of the readings in the manuals are required and _ others 
are optional. Required readings are contained in learning 
activities and are indented to set them apart from the module 
text. These readings are required because they cover material not 
otherwise covered in this course. The optional readings are 
mentioned within the module text and are designed to help you in 
two ways. First, they teach you more about a given topic. 
Second, they offer another explanation in case you have trouble 
understanding the explanation in this course. 


In addition, you will need the manuals to look up _ the 
specifics involved in invoking the various services. This is 
especially true for the executive directives, system library 
routines, and File Control Service calls. 


Keep the module objectives in mind. If a skill is listed as 
an objective, be sure to master it. Later modules may depend on 
this skill. 


The module text contains many example programs to show you 
how to use the skills you are learning. All of the example 
programs in this book should be available on-line. The standard 
location for these files is UFD [282,1] on your system disk. 
Check your system and if the files are not located there, check 
with your course administrator to find out where they are’ located. 
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Do not modify the files in UFD [202,1] or in their original 
location. Instead, copy the files you plan to use to your own UFD 
and use them there. In that way, the original files in UFD 
[202,1] will remain intact for other students. 


Each example program contains the following: 


e Source code, with line numbers added 
e A sample run session 
e Bulleted items which are described in the text. 


Line numbers have been added to the source code to. ease 
referencing during a group discussion. These line numbers are not 
part of the actual source file. The source code also contains the 
name of the file which contains the code on-line. Following this 
is a brief description, telling what the example does. Any 
special assemble and task-build instructions, and any special 
install and run instructions’ follow this. Only special, 
nonstandard instructions are included. The code itself includes 
line comments plus some additional comments. 


The sample run session shows what happens during a typical 
run of the task. Any special install and run instructions are 
shown in the run session. 


The bulleted items match the example notes in the text, which 
describe the code in more detail. Study the examples and the 
notes that describe them carefully. 


In the module on Using File Control Services, many of the 
examples create output files. A dump of any created file follows 
the run session. The file dumps were created using the DMP 
utility. 


If the examples are available on-line, assemble and 
task-build them, and then  run_ them. This will help you to 
understand the examples better. Many of the tests/exercises ask 
you to make minor changes to existing examples, and then run them 
again. Do the tests/exercises for a module in the Tests/Exercises 
book only after you have done all of the reading and have run the. 
example programs. If you prefer, you can do them aS Soon as you 
cover the necessary material in the module. The same 
Tests/Exercises book is used in this course and the Programming 
RSX-11M in FORTRAN course. Do all tests/exercises except those 
which specifically say in FORTRAN. All exercises have solutions 
in the Tests/Exercises book. In addition, any solutions involving 
programs should be available on-line, in UFD [202,2]. Compare 
these solutions to your own. 
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If you have mastered the module objectives, ask your course 
administrator to record your progress on your Personal Progress 
Plotter. You will then be ready to begin a new module. If you 
haven't yet mastered the module objectives, return to the module 
text for further study. 


With a self-paced course, it is impossible to give a schedule 
that applies to all students. The amount of time that students 
spend on a module depends on both their experience and their 
interest in the topics in that module. Use Table 1 as a guide 
when you set your schedule. 


In addition to the 18 modules, the Student Workbook contains 
several appendices, plus a glossary. The appendices are: 


Appendix A -—- Supplied Macros. This appendix contains 
documentation on how to use the macros supplied with the 
course. In addition, it includes the source code for all of 
the macros and any subroutines which they require. 


Appendix B - Conversion Tables. This appendix contains a 
table for converting between decimal and octal, and among 
words, bytes, and memory blocks. It also contains a table 
for converting from active page registers (APRs) to virtual 
addresses. 


Appendix C -—- FORTRAN/MACRO-11 Interface. This appendix 
contains an explanation of the techniques which you should 
use to write a FORTRAN callable subroutine in MACRO-11. Tt 
also explains how to call such a subroutine from MACRO-11. 


Appendix D - Privileged Tasks. This appendix contains a 
description of the various types of privileged tasks 
supported under RSX-11M, and how to create them. 


Appendix E - Task Builder Use of Psect Attributes. This 
appendix contains a description of the effect of Psect 
attributes on how the Task Builder collects together 
scattered occurrences of program sections. 


Appendix F - Additional Shared Region Topics. This appendix 
contains several additional shared region topics. They are: 
overlaid shared regions, referencing multiple regions from a 
Single task, interlibrary calls, and cluster libraries. 
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Appendix G - Additional Examples. This appendix contains the 
source code for any program examples which are required for 
the Tests/Exercises but are not included elsewhere in the 
Student Workbook. These examples should also be available 
on-line, under UFD [2@2,1]. They are included here in case 
they are not available on-line on your system. 


Appendix H - Learning Activity Solutions. This appendix 
contains the solutions to any Learning Activity questions in 
this course. After you do a Learning Activity, check your 
answers against those provided. 
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Table SG-1 Typical Course Schedules 
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USING SYSTEM SERVICES 


INTRODUCTION 


RSX-11M provides system services which perform many 
operations that are commonly needed by user-written application 
programs. Skillful use of these services can: 


e Improve the efficiency of your tasks, reducing size and 
execution time 


e Decrease the time it takes to code and debug your tasks 

e Increase the reliability of your tasks 

e Provide you with controlled access to system features 

e Benefit the overall performance of your system. 

The first step in learning to use these services is 
understanding what services exist, how you can request them from 
within your task, and how the services are delivered to you. 


These topics are explained in this module and the following 
module. 


OBJECTIVES 


1. To identify the facilities provided through system 
services 


2. To list the ways in which system services may be provided 
to a task 


3. To list the various system libraries and the facilities 
they provide. 


RESOURCES 


1. RSX-11M/M-PLUS Executive Reference Manual, Chapter 1 


2. IAS/RSX-11 System Library Routines Reference Manual, 
Chapters 1 through 6 
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WHAT IS A SYSTEM SERVICES? 


An RSX-11M system service is a function or service performed 
for a running task. It is performed during the task's execution. 
The software which provides the service is either in the Executive 
itself or in other system supplied code. 


WHY SHOULD YOU USE SYSTEM SERVICES? 


To Extend the Features of Your Programming Language 


System services offer you additional features, not inherently 
a part of your programming language. Examples of this are: 


1. Accessing shared resources in a properly synchronized way 
2. Performing I/O operations in MACRO-11 

3. Coordinating among multiple tasks 

4. Controlling memory allocation and mapping 

5. Interacting with the Executive 

6. Performing often needed functions, such as: 


a. Numeric conversion of ASCII data typed in at a 
terminal to binary format for internal use 


b. Editing, and conversion, to produce suitable output 
messages which include data generated at run time. 


_To Ease Programming and Maintenance 


DIGITAL provides the code to perform these services. 
Therefore, you will need less time to develop working programs. 
The supplied code has a well defined modular structure, which 
makes it easier to design your programs. 


The code for system services is well debugged. This makes it 
easier to debug and maintain programs, since there are fewer 
potential points of failure and only your written code needs to be 
debugged. When maintenance is required in the code for the 
supplied system services, patches are released with clear-cut 
installation procedures. . 
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To Increase Performance 


The supplied code to perform system services is’ generally 
efficient MACRO-11, which assures minimum execution time. In 
addition, it is often possible to share the code among. several 
different tasks, with minimal additional overhead. This can 
result in any or all of the following performance gains. 


Increase in your task's throughput 

Increase in your system's throughput 

Increase in memory usage efficiency on your system 
Decrease in your task's size 

Increase in available space on mass storage volumes 


WHAT SERVICES ARE PROVIDED? 
The system services can be divided into a number of classes. 


For each, a few examples are given to show you the kinds of 
services which are available. 


Note that a number of these services which are provided to 
tasks parallel those provided to operators through DCL commands. 


System and Task Information 


You can obtain information from the system. For example, you 
can: 


e Obtain information about your task 
- Its priority 
- Its logical unit (LUN) assignments 
e Obtain information about a partition on the system 
- Its base address 
- Its length 


e Obtain the current time and date 
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Task Control 

You can start up and stop tasks, and alter task states. For 
example, you can: 

e Request another task to run 

e Abort a task 

e Suspend or resume a task 

e Alter the running priority of an active task 


Task Communication and Coordination 


You can create a set of tasks that communicate with one 


another, 
example, 


as well as coordinate the interaction of the tasks... For 
you can: 


Send data from one task to another. 


Have one task notify other tasks that an event has 
occurred (e.g., that a job has been completed). 


Have one task pass a command to another task, and have it 
obtain an indication from the other task about the status 
of the execution of the command. 


I/O Peripheral Devices 


on You can interact with peripheral devices on your system. For 
example, you can: 


Write data to or read data from a peripheral device. 
Attach a device for exclusive use by a task. 


Read or set variable characteristics of a device (e.g., 
for a terminal - baud rate or hold screen mode). 


File and Record Access 


You can access files, including individual records within a 


file. 
® 


For example, you can: 


Create a file. 


Read blocks from or write blocks to ae# file on a 
block-by-block basis. 
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e Read records from or write records to a file. The records 
may be of different lengths, and not exactly one block 
long. 


e Extend or truncate an existing file. 


File and Record Access Systems 


The two access systems available under RSX-11M are File 
Control Services (FCS) and Record Management Services (RMS). Both 
offer an interface between tasks and the Files-ll structure used 
to maintain disk directories and files. 


FCS is the standard access system supplied with RSX-11M. 
Many of the utilities (e.g., PIP, EDT, the Task Builder) use FCS 
for their file interface. RMS offers all of the FCS functionality 
plus capabilities not available with FCS, such as indexed files 
(records that are accessible by a key field value) and more 
sophisticated file sharing. A more complete discussion of the 
facilities offered by FCS and RMS, and a comparison of the _ two, 
appears in Module 9, on File I/O. 


Memory Use 


You can use system services to control the amount of memory 
your task useS or to permit several tasks to share an area of 
memory. For example, you can: 


e Run a task in less memory than its total size, by using 
overlays to load only needed pieces of the program at one 
time. 

e Allocate space in memory for a temporary work buffer, and 
then return that space to the system when the task is 
finished using it. 


e Share a data area in memory among several tasks. 


e Share a single copy, in memory, of a commonly’ used 
subroutine among several tasks. 
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OTHER SERVICES AVAILABLE 


You can use system services to perform often needed 
functions. For example, you can: 


@e Save and restore all or a subset of the registers when 
writing a subroutine. 


e Perform extended integer and double precision 
multiplication and division. 


e Convert data from ASCII to internal binary. 


e Convert and format output data produced at run time _ into 
printout and/or display messages. 


These services are generally supplied as subroutines’ located 
in the system object library (LB:[1,1]SYSLIB.OLB). Most of the 
subroutines are documented in the IAS/RSX-11 System Library 
Routines Reference Manual. A few of the Subroutines will be 
covered in detail in this course. However, most will not. Table 
1-1 gives examples of specific functions performed by some of the 
subroutines. 
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Examples of Use of Other Services 


Table 1-l 
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HOW SERVICES ARE PROVIDED 


Services are provided uSing two different methods. 


1. The Executive is invoked by the task to perform the 
service (an executive directive). 


2. The code to perform the service is placed directly into 
the task. 


Executive Directives 


Figure 1-1 shows how the first method works. The following 
notes are keyed to the figure. 


@ The user task makes a service request and invokes’ the 
Executive. 


@ The Executive takes control and performs the service. 


- Calls device drivers as needed 
- Requests other tasks as needed 


@ The Executive returns control to the user task, at the 
instruction following the service request. 


Figure 1-2 shows a more complex version of method 1. In this 
case, Task A and Task B interact through the Executive. 


Task A starts up and at some point needs Task B to do_- some 
work, for example, perform a calculation. Task A sends the data 
to Task B, requests that Task B run, and then waits until Task B 
sends back the answer. Task B starts running, performs the 
calculation, and then sends the answer back to Task A. Task B 
also notifies Task A that the job is finished. Task A then starts 
up again and uses the answer. The steps outlined above for Figure 
1-1 would actually be used several times in this example. 
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Figure 1-1 Using Executive Directives to Service a Task 
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Figure 1-2 Using Executive Directives to Receive Services 


from Other Tasks 
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Code Inserted into Your Task Image 


The second method for providing system services is 
illustrated in Figure 1-3. The code to perform the service is 
extracted from a system library and inserted directly in the user 
task. For system macros, the machine code resulting from the 
Macro expansion is executed in place. For system subroutines, the 
subroutine call results in a transfer of control to the subroutine 
code, located in another part of the user task. 


Certain services must be provided by invoking the Executive. 
Any service which involves’ synchronization or access to shared 
resources must be coordinated by the Executive. For example, if a 
request activates another task, the Executive must enter the task 
in the active task list, which sets the task up to compete _ for 
memory space and then CPU time. It is much easier to have the 
Executive coordinate all the tasks, rather than require that each 
task check with every other task before using a shared resource, 
Also, any activity that involves communication or coordination 
among multiple tasks usually must be performed by the Executive. 


Placing the code in the user task is appropriate for a 
service which is performed independently by a task. For example, 
if a task converts an ASCII decimal value which is input at a 
terminal to binary for internal use, there is no need for the 
Executive to coordinate that activity. It does not affect shared 
resources or other tasks. 


If a service can be provided with code inserted in the task 
and that service is needed often by a number of different tasks, 
it is possible to share one copy of the code among several tasks. 
Using special techniques, often used subroutines can be collected 
together and a single copy of each Subroutine can be shared in 
memory among several tasks. The procedure for producing and using 
a shared collection of Subroutines, called a resident library, is 
discussed in the Static Regions module of this course. 


Some of the services discussed in this course are provided by 
making Special requests when you task-build your task. In some 
cases, the Task Builder transparently places code directly in your 
user task. In other cases, it sets up your task in a special way 
to provide the service. We will discuss the techniques’ for 
accessing services with the Task Builder in later modules. 
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Figure 1-3 Code Inserted into Your Task Image 
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SYSTEM LIBRARIES 


Table 1-2 contains a list of the libraries which are used 
during program development of a task using system services. They 


are uSually located in LB:{1,1]. RSXMAC.SML is the System macro 
library searched by default by the MACRO-11 assembler. SYSLIB.OLB 


is the system object library searched by default by the Task 
Builder. 
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Table 1-3 contains a list of the shareable resident libraries 
which may also be on your system, depending on your installation. 
You will learn how to use these resident libraries in Module 7, on 
Static Regions. Check with your system manager to find out 
whether the preferred method of including these routines is 


through linking the code into your task image or using the 
resident libraries. 


Table 1-3 Resident Libraries 


Now do the tests/exercises' for this module in the 
Tests/Exercises book. They are all written problems. Check your 
answers against those provided in that book. 


If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will than be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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DIRECTIVES 


INTRODUCTION 


Once you know the various system services available, you need 


to know how to write programs which use them. This module 


explains more about the services available through executive 
directives and how to make various directive calls. 


1. 


Ze 


OBJECTIVES 


To write programs in MACRO-11 which use directives 


To use information returned by the Executive to perform 
error checking 


To use event flags and asynchronous system traps (ASTs) 
with directives. 


RESOURCES 


RSX-11M/M-PLUS Executive Reference Manual, Chapter 1 and 
2, and specific directives in Chapter 5 


IAS/RSX-11 System Library Routines Reference Manual, 
Chapters 4 and 5 
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INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK 


Directive Processing 


The sequence of steps outlined below details how a_ directive 
is invoked and processed. The following notes are keyed to Figure 
2-1. 


Executive Code User Code 


@ The user creates a Direc- 
tive Parameter Block (DPB) 
which contains all the 
information the Executive 
needs to process the dir- 
ective. 


@ #ither the Directive 
Parameter Block itself or 
its starting address is 
pushed onto the stack. 


a) The user task issues an 
EMT 377 instruction, 
causing a trap into the 
Executive. 


@ A dispatcher routine 
retrieves the Directive 
Parameter Block, and 
checks it to find out 
which directive 
has been requested. 


@ The dispatcher routine 
calls the appropriate 
Directive routine to 
execute the directive. 


Si 
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Executive Code User Code 


@ After executing the dir- 
ective, the Executive 
returns control to the 
user task and returns 
directive status. 


@ The user task checks the 
directive status and takes 
appropriate action. 


Use macros in the system macro library, LB:{1,1] RSXMAC.SML 
to issue directives. 


Most directives pass control back to the user task. Certain 
directives by their nature do not pass back to the user task. The 
Exit Task directive, for example, causes the task to exit. 
Control passes back to the user task only in the case of a 
directive error. 
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Figure 2-1 Directive Implementation 


Functions Available Through Executive Directives 


Table 2-1 lists many of the Executive directives which are 
available on your system. For a complete list of the directives 
in each group, see section 5.1 on Directive Categories, in the 
RSX-11M/M-PLUS Executive Reference Manual. 


Many of the functions available are discussed more fully in 
this module, and in the modules on Using the QIO Directive, Using 
Directives for Intertask Communication, and Dynamic’ Regions. No 
attempt is made to discuss every executive directive. You should, 
however, at the end of this course, know enough to be able to look 
up any directive in the manual and invoke it. 


Each directive is documented individually in Chapter 5 of the 


RSX-11M/M-PLUS Executive Reference Manual. The directives appear 
there in alphabetical order by MACRO-11 name. 
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The Directive Parameter Block (DPB) 

The Directive Parameter Block is set up as the first step in 
invoking an Executive directive. It contains all the information 
the Executive needs to perform the requested service. This 
includes a Directive Identification Code (DIC) which identifies 


the Executive directive being requested. See Figure 2-2 for a 
picture of the Directive Parameter Block layout. 


The length of the DPB is included because its length varies 
depending on which directive is being invoked. The rest of the 
DPB is built from the arguments specific to the particular 


directive. 
DIRECTIVE 
stele IDENTIFICATION 

CODE 

WORD 1 

WORD 2 

WORD 3 

WORD 4 


FROM DIRECTIVE 
ARGUMENTS 


WORD M-1 
WORD M 


Figure 2-2 The Directive Parameter Block 


TK-7512 
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Macros are provided in the system macro library 
[LB:[1,1]RSXMAC.SML] to set up the DPB and invoke each executive 
directive. The format of the macro call is as follows. 


XXXXSX argl,arg2,arg3,...,argn 
Example: 


GLUNSC 4,BUFF 


The macro name determines the DIC and the length of the DPB; 
the arguments in the macro call are used to build the rest of the 
DPB. The DPB for the example given is as shown below. 


BUFF 


For additional information on the macros for each directive, 
see the individual directives in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual. 


The Executive preserves (Saves and restores) all task 
registers when a task issues a directive. 


The Directive Status Word (DSW) 


Upon completion of directive processing, the Executive 
returns a code in the Directive Status Word which gives the status 
of the request. The DSW is located in the task header at location 
SDSW, a global symbol which can be used to reference the value 
directly. Successful completion is usually indicated by a DSW 
value of +1 (IS.SUC). 


A negative value indicates an error. Different negative 
values correspond to different sources of errors. These values 
and their general meanings appear in Appendix B of the 
RSX-11M/M-PLUS Executive Reference Manual and in the RSX-11M 
Mini Reference Manual. In addition, specific error values and any 
special meanings are documented with each individual Executive 
directive call in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual. 


42 


DIRECTIVES 


In addition to setting the DSW, the Executive clears’ the 
carry bit to indicate successful directive execution and sets the 
carry bit to indicate failure. You can check for errors using a 
BCC or BCS instruction immediately after the directive call. In 
that case, access the actual DSW value only if you need it. 


Sample Program 

Example 2-1 illustrates the use of the Request Task and _ the 
Exit Task directives. The directives are given below, along with 
a description of their functionality. 

The Exit Task Directive 


- Format: EXITSS (no arguments) 


- Used to make a task inactive and to free up the system 
resources it uses. 


The Request Task Directive 


- Format: RQSTS tsk 
where tsk is the name of the task to be requested 


ROSTSC TASKA 
- Used to request the specified installed task 


- Offers the same functionality as the DCL RUN (immediately) 
command for an installed task. 


Before using any directive in a program, always read over the 
description of that directive in Chapter 5 of the RSX-11M/M-PLUS 
Executive Reference Manual. Specifically, pay attention to the 
different directive parameters and their meanings. See section 
5.3 (on System Directive Descriptions) for an explanation of the 
organization of the directive desciptions and what elements are 
included. 

Each program example in this course contains the following: 

e Source code, with line numbers added 

e A sample run session 


e Bulleted items which are described in the text. 
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See the Student Guide for additional information about how to 
use the program examples. 


The following comments are keyed to the example. 


The macros for invoking directives must be specified to 
the assembler in a .MCALL statement. 


A number of special macros have been supplied with this 
course to assist you in class. Since you don't yet know 
how to issue the QIO directive, which is covered in the 
next module, the TYPE macro is supplied to perform writes 
to TI:. 


Example: 
TYPE <HELLO THERE> 


issues a QIO directive to display the text 
"HELLO THERE" at your terminal. 


The use of the supplied macros is documented in Appendix 
A, along with the source code for all macros and any 
internal subroutines they call. 


Invoke the Request Task directive. The task name must be 
the installed name (...PIP), not.just PIP. 


The carry bit is set by the Executive in the case of an 
error and is cleared in the case of success. Always check 
the status on return from an executive directive. 


The only case in which control will return to the user 
task after an EXITSS call is if a directive error occurs. 
This is very unlikely to happen. 


This is an easy way to display the DSW value. The I0OT 
instruction causes the Executive to abort the task and 
display all registers at TI:. 


ON THE RUN SESSION. A run session iS included for each 
example program. 


The simple method for displaying directive error messages is 
used here to keep things simple. This technique may be useful in 
the early stages of debugging a program. Later, this code should 
be replaced with code which displays more readable error messages. 
Techniques for doing this are covered in the next module. 
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1 *+TITLE REQUES 

2 +ITENT /0O1/7 

3 »ENABL LOC ’ Enable lower case 

4 > + 

ba § FILE REQUES.MAC 

& 3 

7 § This task disrelays @ messager then reauests FIFsy and 

8 5 Exits 

9 9 

10 + Assemble and task-huild instructionsy to include 

11 § surPrelied macros and subroutines? 

12 5 

13 5 MACRKO/LIST L&tRAsy LIPROGMACS/LIBRARY »sdevi Cufd JTREQUES 
14 3 LINK/MAF REQUES » FROGSUBS/LIBRARY 

15 5 

16 +MCALL EXIT#SsRAQSTSEC § External system macros 
17 5+ 

18 5 TYFE is 8 macro surrlied in the macro library 
19 i LEIELyLIFROGMACS.MLE for doins I/Q. It issues QI0 
20 § directives for you. TYFE calls subroutines in the 
ei ys ObJect library LEI Cy lLIFROGSUBS.OLE. 
coe tae) j~ 
23 *MCALL TYFE 5 External surrlied macro 
24 Fy 
25 5 Ttiselay stertur text 


26 START? TYFE <REQUES HAS STARTED AND WILL REQUEST PIF> 


27 3 
28 y Reauest FIP 
29 ROST$C ...PIP 5 
O30 BCS ERR $ 
34 ; 
@ x EXIT$S ; 
33 § Error code 
@[ 22 ERR: MOV $LISU » RO ; 
35 1OT 3 
36 ; 
37 sEND START 


Rum Session 


“RUN REQUES 


REQUES HAS STARTED AND WILL REQUEST FIF 


PIP SSL 


i 


lisrplay messade 


Reauest PIF 

Eranch om directive 
error 

Exit 


Move [ISW for disrelayw 
Trar and diselay 
resisters 


Example 2-1 Requesting a Task 
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DIFFERENT FORMS OF THE DIRECTIVE CALLS 


There are three different forms for each directive call, 
which correspond to three different methods for setting up the DPB 
and invoking the directive. For each directive call in a program, 
you may select which form to use. 


With two forms, the $ and the $C, the DPB is set up in a data 
area of your task at assembly time. In the $ form, you use one 
system macro to set up the DPB, and another system macro at- run 
time to invoke the directive. In the $C form, you use just one 
macro to both set up the DPB and invoke the _ directive. The 
assembler separates the DPB setup into a data area for you. In 
the $S form, the DPB is set up on the user stack at run time and 
the directive is invoked immediately afterwards. As in the $C 
form, only one system macro is needed to both set up the DPB and 
invoke the directive. 


Decide which form of each directive call to use based on the 
following. 


e Task size 
e Run time efficiency 
e Programming ease 


e Knowledge of directive parameters, whether known at 
assembly time or at run time 


e Requirements for reentrant code (e.g., if the code is 
contained in a shareable library). 


Each of the three forms is further described below, using the 
Set Event Flag directive (SETFS) as an example. 


The $ Form 


Figure 2-3 shows the $ form, so named because the last 
character in the macro name is 'S$' (e.g., ROSTS, ABRTS, etc.). In 
the source code, use a system macro to set up the DPB in a data 
area, specifying a label to identify it. In the example, LABEL is 
the label for the DPB set up by the macro SETFS$. The DPB is_ set 
up at assembly time. The first word of the DPB contains the DPB 
length in the high-order byte and the DIC in the low-order byte. 
The next word contains the event flag number argument. Any 
additional arguments would appear in successive words. 
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TASK IMAGE 


HEADER 


SOURCE EXPANDS TOO ofl ™ 


LABEL: SETF$ 52.———,» JLABEL: .BYTE  33.,2 
° WORD 52. 


eel : START: : 


DIRS #LABEL MOV #LABEL,-(SP) 
: EMT 377 


TASK CODE 


XXXXXXX 
XXXXXXX 


XXXXKXKX 
XXXXXXX 


DPB IN DATA AREA: 


TK-7730 


Figure 2-3 The 'S' Form 
e Use the $ form of the directive macro to set up the DPB in 
the data area at assembly time. 
e Use DIRS macro to initiate the directive at run time. 


e The DIRS macro pushes the DPB starting address onto’ the 
stack, then traps to the Executive. 


e Arguments in the $ form must be valid for .BYTE, .WORD, or 
~-RAD5@ assembler directives. 


valid arguments: 


invalid arguments: #14.,#204,#TASKA,@BUFF,R2 


- decimal point following a numeral 
indicates that it is in base 18 notation. If no decimal point 
follows a numeral, it is usually in base 8 notation. The 
exception is when base 18 is clear from the context; e.g., 16 
bits. 
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Use the separate system macro DIR$ at run time to invoke’ the 
directive, specifying the label of the DPB. This macro pushes the 
starting address of the DPB onto the stack and then traps to the 
Executive. The label LABEL, which corresponds to the starting 
address of the DPB, is specified in the DIRS call. If other 
directives are invoked in the same task, DIRS is used each time, 
with the appropriate address (or label) specified. 


Arguments in the $ form of the directive must be valid 
arguments for .BYTE, .WORD, or .RAD5@ Assembler directives. MThis 
is necessary because the macros contain .BYTE, ~WORD, or  .RAD5@ 
assembler directives. See the examples that accompany Figure 2-3. 


This form of the directive is run time efficient. In 
addition, if the same directive is used later in the program to 
clear another event flag (e.g., 53.) it is possible to use the 
same DPB for both calls. Offsets within the DPB are defined by 
global symbols. Hence, at run time, the instructions INC 
LABEL+C.LEEF or MOV #53.,LABEL+C.LEEF would change the existing 
DPB for reuse, uSing another DIRS #LABEL call. This saves on task 
space, especially for directives with many arguments. 


One drawback of this method is that it is harder to use 
because two separate macros are needed for each directive 
invocation. Another is that it is not reentrant if the DPB is 
changed at run time. For example, reentrant code is required in 
shareable subroutines. 
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The $C Form 


Figure 2-4 shows the $C form, so named because the last 
characters in the macro name are 'SC' (e.g., ROSTSC, ABRTSC, 
etc.). This form functions similarly to the $ form, but it is 
easier to use because the DPB setup and actual directive 
invocation are combined into one macro call. The assembler 
separates the DPB setup into a data area in a separate Psect named 
SDPB$$. At run time, a pointer to the DPB is pushed onto the 
stack when the directive is invoked, as in the $ form. 


Arguments for the SC form must also be valid arguments’ for 
~-BYTE, .WORD, or .RAD5@ assembler directives. Also, there is an 
additional optional argument for all $C form calls which is only 
necessary if a call is made from a Psect other than the default 
blank Psect. This argument specifies the Psect from which the 
call is made. This allows return to this Psect for the directive 
invocation and other code. In Figure 2-3, the Psect PROGS 
contains the main code. 


An advantage of this method is that it is easier to use than 
the $ form and is just as efficient at run time. One restriction 
is that a given DPB cannot be accessed and modified at run time. 
Therefore, to clear event flag 53., a separate CLEFSC 53. 
directive is required, which generates a separate DPB. So for 
repeated use of a directive, the $C form requires more task space. 
Another restriction, due to the inaccessibility of the DPB at run 
time, is that all directive arguments must be known at assembly 
time. One other advantage of the $C from is that it is always 
reentrant, since the DPB cannot be changed. 
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SOURCE EXPANDS TO 
PSECT PROGS PSECT PROGS 
START: « START: 
SETF$C 52.,PROGS PSECT $DPB$$ 
° BYTE 33.2 
* WORD __ ‘52. 
‘PSECT PROGS 
MOV #$$$, - (SP 
EMT 377 


Figure 2-4 The $C Form 


Using the SC Form: 


TASK IMAGE 


HEADER 


TASK CODE 


PSECT PROGS 


XXXXXXX 
XXXXXXX 


PSECT $DPB$$ 


XXXXXXX 
XXXXXXX 


TK-7731 


e Needs only one macro call. 

e Sets up the DPB in the data area at assembly time. 

e The SC form, as in the $ form, also pushes the DPB address 
onto the stack and traps to the Executive at run time. 

e Optional argument specifies the current Psect if other 
than the blank Psect. 

e Arguments must also be valid for .BYTE, .WORD, or .RAD5@ 


assembler directives. 


58 


DIRECTIVES 


The $S Form 


Figure 2-5 shows the $S form, So named because the last 
characters in the macro name are 'S$S' (e.g., ROSTSS, ABRTSS, 
etc.). In this form, the DPB setup and the directive invocation 
itself are combined into one macro call, as in the $C form. 


However, unlike either the $ or the $C form, in the $S_ form, 
the DPB is built at run time instead of at assembly time, and it 
is built on the stack instead of in the task'sS data area. This 
means that all arguments must be valid source arguments for MOV or 
MOVB instructions. See the examples with Figure 2-5. 


One advantage of this method is that the same call can be 
used with different arguments, since a new DPB is built with each 
executive directive macro call. Therefore, you can place 
parameters which aren't known until run time in registers or data 
areaS. You can then specify the registers or the addresses of the 
data values as arguments in the directive call. 


Another major advantage is that the code can be reentrant 
even if the directive arguments are modified. For example, a 
register may be used aS an argument. Because each task has its 
own registers, each task has its own independent copy of the 
argument. 


The major disadvantage of this form is that it executes’ the 
slowest of the three forms, because every word of the DPB must be 
pushed onto the stack immediately before invoking the directive. 
The more arguments the directive has, the longer it takes. 


If a directive has no arguments (e.g., EXITS), it is just as 
run-time efficient to use the $S form, because the complete DPB is 
only one word long. Therefore, it takes one instruction to push 
the complete DPB onto the stack in the $S form. It also takes one 
instruction to push the address of the DPB onto the stack in the $ 
and $C forms. Any directive which has no arguments (e.g., Exit 
Task, Suspend Task) is available with only the $S form. 
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TASK IMAGE 


HEADER 


STACK 


SOURCE EXPANDS TO 
a : TASK CODE 
START: e START: e 
e MOV (PC)+,—(SP) XXXXXXX 
BYTE 33.,2 XXXXXXX 
EMT 377 XXXXXXKXX 


XXXXXKX 


DPB ON STACK 
(AT RUN TIME): 


TK-7732 
Figure 2-5 The $S Form 
Using the $S Form: 
e Needs only one macro call. 


e The $S form pushes complete DPB onto the stack at~= run 
time, then traps to the Executive. 


e Arguments must be valid source arguments for MOV 
instructions. 


valid arguments: #15.,#204,#BUFF,R1 
possible misused arguments: 15.,204,BUFF 


Use 15., 284 or BUFF only if you want the contents of 
those locations for the directive parameters. 
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One other disadvantage of using the $S form arises when’ task 
or partition names are specified as arguments. These arguments 
must be in Radix-5@ format in the DPB. If the $C or $ form is 
used, the macro converts the ASCII name specified as an argument 
to Radix-5@ format. If the $S form is used, you must place’ the 
name in a data area in Radix-5@ format, then specify the address 
of the data in the macro call. You can either use a_e .RAD59 
assembler directive at assembly time or the SCAT5 subroutine. See 
Appendix A of the IAS/RSX MACRO-11 Reference Manual for a 
description of the Radix-5@ character set. Also, see 6.3.6 9 (on 
the .RAD5@ assembler directive) in the Same manual for a 
discussion of Radix-5@ format. 


Examples 


Examples 2-2, 2-3, and 2-4 illustrate the use of the _ three 
forms of the directive calls. All three forms send a 13(18) = 13. 
word packet of data to a task RECEIV. The source code for RECEIV 
follows the code for Example 2-3. Don't worry yet about the 
actual mechanics of how to set up sender tasks and receiver tasks. 
These are discussed in the module on Intertask Communication. 
Just compare the uses of the different forms of directives. The 
following notes are keyed to all three examples. 


@ The .MCALL statement declares’ the particular macro 
directive call or calls to be used, including the form. 


@ Data area setup requirements: 


$ form: SDATS directive sets up the DPB in the data 
area. 


$C form: Nothing is set up separately. The Assembler 
sets up the DPB in a data area for you. 


$S form: Normally, nothing is set up in a data area. 
' Task names are an exception, since they must 
already be in Radix-5@ format. Therefore, 
the task name is set up in Radix-5@ format 
in the data area. The argument in the $S 
call is the address of the task name. 
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@ Executing the directive call. 
$ form: Use the separate DIRS macro. 


SC form: Use the single SDATS$S call. The DPB is’ set 
up at assembly time by this macro. Just the 
directive invocation is performed at run 
time. 


$S form: Use the SDATSS call. The entire DPB is 
pushed onto the stack at run time and then 
the directive is invoked. 


@ ON THE RUN SESSION. First run the sender. Then run _ the 
receiver to receive and display the data. 


Note the difference in the form of the arguments in the §$S 
form. These argumentS are source arguments for MOV or MOVB 
instructions. For the $ and $C forms, the arguments are arguments 
for .WORD, .BYTE, or .RAD5@ Assembler directives. 


1 +TITLE SEND 

2 eIQENT /0O1/7 

3 *ENABL LE § Enable lower case 

4 i+ 

5 ¢* FILE SENII.MAC 

é 3 

7 ¢ This task sends a buffer of 13. words of data to the 
8 § task RECEIV for rrocessinsg. It sets common event fleas 
9 $ 33. when the data is aueued for RECEIV 

10 ; 

ii ¢ It uses the $ form of the Send Data directive 

12 ; 

13 5 Assemble and task-huild instructions? 

14 ; 

15 ; MACRO/LIST LBifCi» 1 IFPROGMACS/LIBRARY +: devi CufdISENT 
14 5 LINK/MAF SENDyLB3 Civil IFROGSUBS/LIBRARY 

17 ; 

18 § Install and run instructions? 

19 ; 
20 § This task does mot have to be installed. RECEIV 
ai ; must be installed. 
22 5 

@ 23 sMCALL SDATS/EXIT$S/DIR$ + System macros 

24 *MCALL TYPE § Surrlied macro 
25 


a 


$ 
26 BUFFER? «WORT Le2PeSv4eSyGe7vBe oP y1LO.e1 dev les. d. 
¢ Teta to send 


Example 2-2 Using the $ Form of the Directives (Sheet 1 of 2) 
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29 ’ Create DFE serarstely in ae data area for the # form 
2 30 SENIIN SUATS RECEIVsBUFFERs33. ¢ Set ur DPB for 
31 § directive 
32 5 
© 33 START? DIRS #SENII + Issue directive to 
34 ¢ send data to RECEIV 
35 BCS ERR >’ Kranch on dir error 
36 TYPE “DATA QUEUED TO RECEIV> ¢; Tliselay 
37 y Success messade 
38 EXITS y Exit 
39 
40 ERR? MOV $lISWrR1 + Move [iSW to R1 for 
41 § disrlay 
42 TOT § Trar and disrlay 
43 § resisters 
44 «ENT START 
Rum Session 
SINS RECEIY 
RUN SENT 
TATA QUEVUED TO RECEIYV 
RUN RECETY 
L 2 3 4 a 6 7 3 9 10 11 12 13 
eTITLE RECEIV 
+IQENT /01/7 
*eENABL LC § Enable lower case 


File RECEIV.MAC 


This task receives the data sent by SENDI» SENIICy or 
SENS and disrlays it at TI? 


Sow & Cid Who 
“Qy “ne “Gr “a> com ‘eo 


10 *MCALL RCVEECYEXITSS 

11 *MCALL TYPE 

12 ; 

13 RBUFF ¢ +BLAW 15. ¢ Buffer for data received 
14 BUFF? + BLAKE 80. § Buffer for outrut messade 
18 FMT? *ASCIIT /Z3S4ZUZ4SZULZ4SZUAZAS“ZUZ4AS“~ANAZ4SA“ZAU“Z4S“¢l/ 

16 *ASCIZ SZ4ASZUZ4SZANZ4SZUZ4SA“ZNZ4S“ZNZ4ASZL/ 

17 3 

18 START? RCVOEC +R BUFF ’ Receive from ansone 

19 BCS ERR §* Branch on directive error 
20 §¥ Edit binary data into ASCIT message for disrelayw 

2 MOV RUFF 9 RO § Addr of outeut buffer 

22 MOV ¥F MT o RL ¢ Addr of format strimns 

23 MOV FRBUFF +4 9 R2 * Addr of data receivedy 

2 3 kir sender task name 
2g CALL $EOMSG + Edit ourut message 

26 TYPE #RUFF o RL * Diselay outrut messade 
27 EXIT#S ¢ Exit 

28 93 Error code 

2? ERR? MOV $0NSWekO § Move DUSW for disrlay 

30 TOT + Trar and disrlay 

31 : resisters 

32 *END START 


Example 2-2 Using the $ Form of the Directives (Sheet 2 of 


55 


DIRECTIVES 


1 ¢TITLE SENIIC 
2 ~IQENT /01/7 
3 e*ENABL LC ’ Enable lower case 
4 5+ 
5 > FILE SENDIC.MAC 
6 ; 
7 > This task sends a buffer of 13. words of data to the 
8 § task RECEIV for rrocessing. It sets common event flas 
9 + 33. when the date is aueued for RECEIYV 
10 ; 
1t § It uses the $C form of the Send Teta directive 
12 5 
13 5 Assemble and task-build instructions’ 
14 3 
18 3 MACRO/LIST LEiC1s1IPROGMACS/LIBRARY +s devi CufdISENDC 
16 5 
17 3 LINK/MAF SENDCysLB? Ci ylLIPROGSUBS/LIBRARY 
18 , 
19 § Install and run instructions? 
20 5 
zi 5 This task does mot have to he installed. RECEIV 
22 3 must he installed. 
23 j~ 
24 *MCALL SATSCrEXITSSstIRS ¢ System macros 
25 *eMCALL TYPE § Surrlied macro 
26 ¥ 
27 3 
28 BUFFER? «WORD LetySev4eSebe7 98s e Pe t1 Os, elie v2.13, 
ago + Tate to send 
30 START? SDAT#&C RECEIVs BUFFER’ 33. ¢ Issue directive to 
31 §’ send data to RECEIV 
32 BCS ERR > Branch on dir error 
33 TYPE DATA QUEUE TO RECEIV> $ Diselay 
34 $ SUCCeSs messade 
35 EXIT#SS ¢ Exit 
36 
37 ERR? MOV $0SWeRi1 + Move TSW to R1 
38 ToT § Trar and disreley 
39 ; resisters 
40 «END START 
Rum Session 
2INS RECEIYV 
SRUN SENDIC 
VATA QUEUE TO RECEIV 
SRUN RECEIY 
I 2 3 4 3 6 7 8 9 10 ii 12 13 


Example 2-3 Using the SC Form of the Directives 
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DIRECTIVES 


+TITLE SENTIS 

*+IDQENT /0O1/7 

*ENABL LC * Enable lower case 
FILE SENDS. MAC 
This task sends a buffer of 13. words of data to the 


task RECEIV for rrocessing. It sets common event flas 
33. when the data is aueued for RECEIV 


It uses the $S form of the Send DTlata directive 
Assemble and task-build instructions? 


MACRO/LIST LE¢ Cl» lIFROGMACS/LIBRARY» dev’ CufdISENDIS 
LINK/MAP SENDS»LB? Ci» lL IFROGSUBS/LIBRARY 


Install and run instructions? 


This task does mot have to be installed. RECEIV 
must he installed 


*+MCALL SDATSSrvEXITSS*sDIRS § System macros 
*MCALL TYFE § Surrlied macro 


; 
BUFFER? WORT LeetySv4eSrGo72Bbe vr Oee1Oeelisvil2e. 213, 


a> “Sh WO 


* 


> tiata to send 


Task names must be srecified in Radix-5S0 format for 
the €S form 


TASKNM? .-RADSO /RECEIV/ 
3 


START: SDUAT$S #TASKNMs #BUFFERy #33. § Issue directive to 


$ send data to RECEIV 


BCS ERR > Branch on dir error 
TYPE <DATA QUEUED TO RECEIV> ¢ Display 
¥ SUCCeSS messade 
EXITS § Exit 
ERR? MOV $0SWeRi ¥ Move DSW to Ri 
IOT > Trar and disrlay 
$ registers _ 
+ENDT START 
Run Session 
RECETY 
SENS 
QUEVED TO RECEITYV 
REECE TY 
2 3 4 3 & 7 8 9 10 ji 12 13 


1 


Example 2-4 Using the $S Form of the Directives 
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Repeated Use of a Directive with Different Arguments 


The following sections of code illustrate the use of the 
different directive forms when using a directive several times in 
a program. All three clear event flags 5. to 15., using the 
Clear Event Flag directive 11 times. Note in particular that the 
$ form uses the same DPB over and over again. The $C form macro 
calls result in 11 different DPBs in the data area of the task. 
The $S form uses a register aS an argument and a new DPB is 
generated for each call; but on the stack, not in a data area. 


NOTE 
A discussion of event flags and their uses 
appears later in this module. 
$ Form 
Use the Executive directive first for event flag 5, then 
access and change the DPB for the other ten calls. In the example 


below, the DPB begins at CLEAR. 


-MCALL CLEFS, DIRS 


CLEAR: CLEFS 5. 
START: : 
MOV #5.,RQ 
AGAIN: DIRS #CLEAR 
BCS ERR 
INC RO 
CMP RO,#15. 
BGT DONE 
INC CLEAR+C.LEEF 
BR AGAIN 
DONE: ‘ 
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The $C form cannot access the 
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calls with separate DPBs. 


START: 


DPB; so make 11 


-MCALL CLEFSC 


CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 
BCS 
CLEFSC 


BCS 


CLEFSC 
BCS 


e 
e 
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SS Form 


A new DPB is pushed onto the stack for each call. Use a 
register value for an argument. Make the same call 11 times; 
update the register each time. 


~MCALL CLEFSS 
START: ‘ 

MOV #5,RO 
AGAIN: CLEFSS RQ 

BCS ERR 

INC R@ 

CMP RO,#15. 

BLE AGAIN 


Table 2-2 gives a summary of the three forms of the directive 
call. 
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Summary of the Directive Forms 


Table 2-2 


ee 


sgeuniines 
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ADDITIONAL DIRECTIVE CONSIDERATIONS 


An Alternative Method for Error Checking 


An additional argument can be used to specify the address of 


an error subroutine. 


Format: 


$ Form SC Form 


DCLEF: CLEFS 5 Sr~ 


DIRS #DCLEF, ERROR | CLEFSC 53.,,ERROR 
SS Form 


CLEFSS #53.,ERROR 


| NOTES 
The extra null argument in the $C form is for 
the optional Psect. 


In the $S forn, no '#' is needed on the 
address, since this becomes a JSR PC,ERROR. 
This argument is not moved to the stack. 


In all three cases, the extra argument causes the following 
to be generated: 


s;macro without error address 


z;additional code 
BCC .+6 
JSR PC,ERROR 
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This results in a branch to the instruction following’ the 
directive macro if the directive is executed successfully, and a 
call to the subroutine ERROR if not. It is equivalent to 
including the following code yourself. 


DIRS #LABEL 

BCC OK 

JSR PC,ERROR 
OK: 


Note that in case of an error the transfer to the error 
routine is with a JSR, not a JMP or BR. The result is that the 
return address is pushed onto the stack. If you generate an error 
message and exit, the JSR won't cause any problems because the 
Stack isn't accessed. 

If, on the other hand, you attempt to recover from the error, 
you must remember that the return point is on the stack. You must 
either use a RETURN (RTS PC) or clear the return address off the 
stack if you wish to branch to a different location. 

Examples Using Other Directives 
The following directives are used in Example 2-5. 
e Suspend Task (SPNDSS) 
- Used to suspend itself 
- Can be resumed by another task issuing a Resume task 
directive or by an operator using the DCL CONTINUE 
command 
e Alter Priority (ALTPS) 
- Alters the running priority of an active task 


e Disable Checkpointing (DSCPS$S) 


- Disables checkpointing for a checkpointable task 
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Enable Checkpointing (ENCPSS) 
- Enables checkpointing again after a DSCPS$ directive 
Extend Task (EXTKS) 


- Modifies the size of the task by a positive or 
negative number of 32-word blocks. 


The $S form of SPNDS, DSCPS$, and ENCPS is recommended because 
each directive has no arguments. 


Example 2-5 shows the use of a variety of directives. See 


the run 


demonstration below the source code. The following 


comments are keyed to the example. 


Rl is a directive counter. When several directives are 
used in a program, the counter helps keep track of which 
directive caused an error. After an IOT, n in Rl means 
that there waS an error on the nth directive. R@ contains 
the DSW value. 


Task suspends itself. This allows the operator to use the 
DCL SHOW TASKS/ACTIVE command to examine the task 
parameters. 


The task is loaded at physical address @986152800(8) to 
@9617200(8). SPN means the task is suspended. 


The operator must use the DCL CONTINUE command to’ resume 
the task. 


Suspend again after you disable checkpointing and alter 
the running priority. 


Note the change in running priority (PRI). CKD indicates 
the disabling of checkpointing. 


Suspend again after you enable checkpointing, alter the 
priority back to 5@., and extend the task. 
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Note the change in priority. Note also that the task was 
checkpointed and is now loaded at addresses @1945290(8) to 
@1067200(8). The new task size is 22880(8) bytes, 
compared to 2909(8) bytes before, as shown below. The 
extend is for 200(8) blocks, where each block is 188(8) 
bytes long, which means there are 29000(8) extra bytes. 
See Appendix B for a conversion table of bytes to blocks 
and of octal to decimal. 


Before: 


99617200 (8) 
-9861529008 (8) 


2000(8) bytes 
After: 


91967208 (8) 
-6184529090 (8) 


22008 (8) 
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+TITLE MISC 
eITNENT /017 
+ENABL LC > Enable lower case 


FILE MISC.MAC 


This task uses some miscellaneous Executive directives 
to susrend itself» alter its running rriority,s disable 
ang enable checkrointings and extend its task size. 


Task-build instructions? 


LINK/CHECKPOINT/MAF MISC 
since the task must be checkrointable to allow 
disabling of checkrointing and extending its size 


Install] and Run instructions? 


Install the task. Then Run it to start it ur. 
The task will susrend itself several different 
times. Each times use the command 

SHOW TASKS$MISC/ACTIVE/FULL (MCR ATL MISC) 

to examine the changes. Use the command 
CONTINUE MISC (MCR RESUME MISC) 

to resume the task. 


*+MCALL SPNDSS*sALTFSC»TSCPSS»ENCFSS 
*+MCALL EXTKSCYEXITSS 


Rranch om so0o0d directive 
Call error subroutine 
Susrend to egllow status check 
Make some other changes and then susrernd asain 
ENCF$S § Enable checkrointing asain 
ECS ERRS § Branch on directive error 
ALTFEéC vevsERRS § Return eriority to original 
, 
; 


BCC _ GOOr | 
JSR FC rERRS 


ART? CLR R1 ¢ [Tlirective counter for errors 
SFNDSS § Susrend to allow status check 
RCS ERR1 > Branch om directive error 
Make some chanses and then susrend asain 
ISCFS¢S ’ Disable checkrointing 
BCC OK § Branch on good directive 
JIMF ERR2 > Jume to error code 
‘3 ALTFE¢C +10. § Alter running eriority 
bd 
5 
3 


EXTK$C 200 xtend task size bu 200(8) 
bhlocks 


Example 2-5 Using Several Directives (Sheet 1 of 2) 
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48 BCC ALSOOK 
@Q | 49 CALL = ERR? 
50 ALSOOK! SFNISS 


Branch on good directive 
Call error subroutine 
Susrend again 


“S> Gh “> > “Ge “Ed 


a1 BCC AGNOK Branch onm directive ok 
wa ER ERRS Branch on directive error 
a3 AGNOKS EXITS Exit 
34 y Error handling 
ba kw ERRS8 3 INC Ri § 8 means error on 3rd SFNIGS 
a6 ERR? 3 INC Ri § 7 means error om EXTKR$C 
37 ERR&? INC Ri > & means error on 2nd ALTFSC 
38 ERRS? INC Ri 5 3 means error on ENCPSS 

© ahd ERR43 INC Ri + 4 means error on 2nd SFND¢S 
60 ERR3? INC Ri > 3 means error om ist ALTFEC 
61 ERR2? INC Ri § 2 means error on TSCPeS 
&2 ERR13 INC Ri > 1 means error on ist SPNDS$S 
43 MOV $USWsRO ¢ Move USW for disrelay 
64 TOT § Trae and disrlay resisters 
63 +END START 
Rum Session 


sINS MISC 
RUN MISC 
“SHOW TASKS/ACTIVE FULL MISC 
MISC 055420 GEN 054500 00615200-00617200 PRI - 50. DFRI ~ 50. 
STATUS! SPN -PMII 
Tl - TT11! IOC - 0. RIO ~ 0. EFLG ~ 000000 000000 PS - 170000 
FC - 001264 REGS 0-6 000000 000000 011300 140130 000000 000000 001254 
“CONTINUE MISC 
SHOW TASKS/ACTIVE FULL MISC 
MISC 055420 GEN 054500 00615200-00617200 PRI - 10. DFRI - 50. 
STATUS? CKD SEN -PMD 
Tl -~ TT11t TOC ~ 0. BIO ~ 0. EFLG ~ 000000 000000 FS ~ 170000 
FC ~ 001324 REGS 0-6 000000 000000 011300 140130 000000 000000 001254 
“CONTINUE MISC 
>SHOW TASKS/ACTIVE FULL MISC 
MISC 055420 GEN 054500 01045200-01067200 PRI ~ 50. IFRI ~ 50. 
6 STATUS? SPN ~PMII 
Tl ~ TT1it IOC - 0. BIO ~ 0. EFLG ~ 000000 000000 FS ~ 170000 
FC - 001400 REGS 0-4 000000 000000 011300 140130 000000 000000 001254 
™CONTINUE MISC 
SHOW TASKS/ACTIVE FULL MISC 
ATL «-- Task mot active 


Example 2-5 Using Several Directives (Sheet 2 of 2) 
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This example illustrates a number of techniques for directive 
error checking. At lines 33 and 44, a BCS is used. At lines 36, 
39, 48, and 51, a BCC is used to branch past the transfer to the 
error handling code. 


The transfers themselves also differ. At line 37, a JMP is 
used. At line 4@, a JSR PC is used, while at line 49, a CALL 
which is equivalent to a JSR PC is used. At line 52, a BR is 
used. Finally, at lines 41 and 45, the address of the error 
routine is specified as the last argument of the directive macro 
call. This results in a JSR PC, generated as part of the macro 
expansion. 


All of these get you to the error’ routines. They are all 
equivalent as long as you don't attempt to recover from the error. 
If you do recover, you must remember that a JSR PC or CALL pushes 
a return address onto the stack, as explained in the section on An 
Alternate Method for Error Checking. 


Run Time Conversion Routines 


As) mentioned earlier, the system maintains task names, 
partition names, and certain other data in Radix-5@ format to save 
space. There are times when conversions between ASCII and 
Radix-5@ format need to be performed .at run time. 


You can modify Example 2-1 (REQUES.MAC) so an operator can 
type in the task name at run time. This ASCII name would then 
have to be converted at run time to Radix-5@ format because the 
-RAD5@ assembler directive can only be used at assembly time. The 
subroutine $CAT5 in SYSLIB.OLB is provided for performing this 
conversion. Its use is documented in Chapter 4 of the IAS/RSX-11 
System Library Routines Reference Manual. 


If the Get Task directive (GTSKS$) is used to retrieve task 
information, the task name and partition name are returned in 
Radix-5@ format. If you want to display these, you need _ to 
convert them to ASCII format. The subroutine SC5TA, also in 
SYSLIB.OLB and documented in Chapter 5 of the manual mentioned 
above, is provided for this purpose. 


Additional subroutines are provided for converting between 
binary and octal ASCII (signed or unsigned) and between binary and 
decimal ASCII (signed or unsigned). See Chapters 4 and 5 of the 
IAS/RSX-11 System Library Routines Reference Manual for additional 
information. 
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Notifying a Task When an Event Occurs 


Often a task needs to know when an event has’ occurred. The 
event may have occurred within another task; for example, when 
the task has completed a requested function. The event May 
instead have occurred within the system; for example, when a 
requested I/O operation is completed. The two methods’ for 
implementing synchronization are by using event flags and using 
asynchronous system traps. 


Event Flags 
There are three types of event flags: local, global (or 
common), and group global. Ninety-six event flags are made 


available to tasks, each with a unique number (1(1@)-96(10)). 


Local event flags are provided for each task. There are 
32(18) local event flags, numbered 1(198)-32(180). These flags are 
used to synchronize a task with an Executive service, such as_ an 


I/O transfer. One task cannot reference another task's local 
event flags, so they cannot be used to synchronize tasks with one 
another. Local event flags 25(1@8)-32(1@) are reserved for system 


use and therefore should not be used by a user task. 


Global or Common event flags are provided for synchronization 
among different tasks. There is one set of 32(1%8) global event 
flags for the system, numbered 33(18@)-64(18). These flags can be 
referenced by any task. Global event flags 57(1@)-64(198) are 
reserved for system use and should not be used by user tasks. 


NOTE 

There is no way to protect against other 
tasks using global event flags. Great care 
must be taken to ensure that global event 
flags aren't used at the same time by several 
different users. Check with your system 
manager before using any global event flag to 
ensure that it is not used for some. other 
purpose. 
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There are only 32(18) global event flags available in the 
system. If additional event flags are needed, another set of 
event flags can be created for synchronization among different 
tasks. Group global event flags (32(18)), numbered 65(18)-96(1@), 
can be created for any UIC group number. These event flags can be 
referenced by any task running under the correct group number. 
Therefore, they can be used to synchronize tasks running’ under 
that group number. An additional advantage is that they cannot be 
referenced by tasks running under other group numbers. 


Group global event flags are created using the DCL SET GROUP 
FLAGS CREATE (FLA /CRE in MCR) command or the Create Group Global 


Event Flags (CRGFS$) directive. When users in a group don't need 


them anymore, the group global event flags can be marked for 
deletion using the DCL SET GROUP FLAGS DELETE (FLA /ELIM in MCR) 


command or the Eliminate Group Global Event Flags (ELGFS) 
directive. After that, when all active tasks in the group have 
finished using them, the group global event flags are eliminated. 


Using Event Flags for Synchronization 


Best eet eS 
= Se a= 


SoS 


a 


ae 


= 
ee 
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Examples of the Use of Event Flags for Synchronization 


Examples 2-6 and 2-7 show the use of event flags’ to 
synchronize two tasks. WFLAG creates the group global event flags 
for the group. It then clears event flag 65(18) and waits for 
that flag to be set. SFLAG sets event flag 65(198), which unblocks 
WFLAG. Run WFLAG first, then run SFLAG. 


The following notes are keyed to the examples. 


& Create the group global event flags - The default used 
here creates them for the group number which the task is 
running under. 


} An error is reported if the flags already exist. This 
isn't a fatal error, so we check for this condition. If 
the flags do exist, print a message and continue. 


NOTE 

If the error address had been included in the 
Macro directive call (CRGFSC ,,ERR1), two 
changes must be made to the code. First, the 
check for IE.RSU must’ be made at location 
ERR1. Second, in the case of the nonfatal 
error IE.RSU, the stack will have one extra 
word because the macro does a JSR _ PC,ERRI, 
not a BCS ERR1. Therefore, you would need to 
either use a RTS PC (Synonym RETURN) or, if 
you want to branch to another location, you 
need to pop the return address off the stack 
before branching. 


The flag is in an unknown state at startup. Therefore, we 
must clear the flag before waiting for it to be set. 


Wait for the event flag to be set by SFLAG. This causes 
WFLAG to be blocked. Now run SFLAG. 


Set event flag 65. This allows WFLAG to become unblocked. 
SFLAG now exits. 


When WFLAG is unblocked and continues executing, it starts 
up here. Check for any directive error entering the Wait 
For state, print a message, and exit. 
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—- 


eTITLE WFLAG 
2ITIENT 7/017 
*+ENABL LC : ; Eneghle lower case 


FILE WFELAG.MAC 


Tnis rrogram creates the srour global event flassy» 
clears event flas 65. and waits for it to he set. When 


the fleas is set it writes 8 message and exits. 


Assemble and task-build instructions? 


MACRO/LIST LR& CL» LIPROGMACS/LIBRARY y devi Cufd IWFLAG 


“Gh wh “> “Ee I> “Sd SP KD VP BP DP BP E> GP Ne SP > “te “SS 


Instell 


LINK /MAF 


Rum WELAG» 


and Fun 


WFLAGs LBS CLs LIPROGSUBS/LTIBRARY 


then 


instructions? 


rum SFLAG. At least one of the 


tasks must he instelleds or else the RUN command 
will try to install hoth tasks under the same 
names TTrirte 
*+MCALL EXIT#SsWTSESC »CLEFSCsCRGFSC ¢ Sustem 
y Macros 
*MCALL TYPE ¢ Surrelied macro 
START? CLR RO , RO used to identify 
> the error 
TYPE “WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS> 
CRGF $C § Create srour slahael 
> eavent flads 
RCC OK + Branch om directive ok 
$s if sroue global event flass e@lready exists 
* Just diseleay messase and continue 
CMF $USWe FIE.RSU § Check for efs already 
> in existence 
RNE ERR y Kranch on any other 
ys dir error 
TYFE GROUP GLOBAL EVENT FLAGS ALREADY EXIST: 
OK? TYPE <CLEAR ANT! THEN WAIT FOR EF 635. TO BE SET > 
CLEFSC 65, + Clear event fles 65. 
RCS ERR2 ’ Branch om directive 
+ error. 
WISES$C 65. § Wait for event flag 65 
y+ to he set 
RCS ERRS § Branch om directive 
> error 
TYPE “EF 65+ HAS BEEN SET. WFLAG WILL NOW EXIT> 
EXIT#S 
ERR33 INC RO > RO = 3 if error on 
§ wait for dir 
ERR23 INC RO > RO = 2 if error on 
y clear flags dir 
ERR 3 INC RO > RO = J] if error on 
> create srour flass dir 
MOV $lISWe RL i Flace [DSW in RI 
LOT > Trae and cumr resisters 
+END START 


Waiting for 


an Event Flag (Sheet 1 of 2) 
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Rum Session 


SINS WFLAG 
2INS SFLAG 
2RUN WFLAG 


“WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS 
CLEAR ANT! THEN WATT FOR EF 65. TO BE SET 
RUN SFLAG 


EP 6G. IS BEING SET. THEN SFLAG WILL EXIT. 
EF 65. HAS BEEN SET. WFLAG WILL NOW EXIT 


Example 2-6 Waiting for an Event Flag (Sheet 2 of 
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CON DSH 


eTITLE 
+ IDENT 
+ENABL 


+ 


srour global 


Assemble and 


First 


“ar > > “SP SP SP “SP “CP We SP “EP “Sh “> E> “GP “EP “CP “SP SD 


*MCALL 
*MCALL 


START? TYFE 
SETFSC 
BCS 
EXIT$S 

ERR 3 MOV 
TOT 
eENT 
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SFLAG 
/O1/ 
LC § Enable lower case 


FILE SFLAG+MAC 


This task sets event flags 65. It assumes that the 


event flass have already heen created, 


task~-hbuild instructions? 


MACRO/LIST LBS C1»1IFPROGMACS/LIBRARY » dev: CufdISFLaG 
LINK/MAF SFLAGs» LE CLs 1 JIFROGSUBS/LIBRARY 


Install and Run motes? 


rum WFLAGs then rum SFLAG. At least one of 
the tasks must he instelled+s or else the RUN 
command will try to install both tasks under 

the same names TTrm. 


EXIT#S»SETFSC 
TYFE 


System macros 


; 
§ Suprlied macros 


“EF 65. IS BEING SET. THEN SFLAG WILL EXIT.> 


6356 > Set event fleas 65. 
ERR > Branch on dir error 
y Exit 
€0SWeRi »y Save DSW 
> Trar and dume resisters 
START 


Setting an Event Flag in a Task 
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Asynchronous System Traps (ASTs) 


Asynchronous System Traps (ASTs) are used to detect events 
that occur aSynchronously to a task's execution. Two examples are 
the completion of an I/O transfer and a power up after a power 
failure. We say that they occur asynchronously to a task's 
execution because they occur at unpredictable times, depending on 
conditions which the task cannot control. If a task needs to do 
work while waiting for an event to occur, it can do_ so. and 
periodically check an event flag to detect the event. However, 
this means that the task must stop its work to check the flag. 


Using an AST gives the Executive the responsibility for 
monitoring the event. The Executive will "interrupt" the task and 
transfer control to a special uSer-written routine when the event 
has occurred. This technique is more efficient because the task 
doesn't have to do any checking. It also results in faster 
notification because the task is notified immediately after the 
event occurs. With checking of the flag, it may take a long time 
to notice an event that has occurred immediately after a check. 


Several Executive directives allow the use of ASTs to handle 
synchronization. A complete list appears in the section 5.1.5 on 
Trap Associated Directives in the RSX-1L1M/M-PLUS Executive 
Reference Manual. 


Figure 2-6 shows how an AST works. The following notes. are 
keyed to this figure. 


1) The user specifies an AST routine in an Executive 
Directive. The Executive sets up for the AST. 


@ The Executive returns control to the user task. 


@ when the system determines that the event which 
corresponds to the specified AST routine has occurred, the 
Executive passes control to the AST routine and the task 
executes it before any other user code in the task. This 
means that if the task is executing at the time of the 
AST, the task is “interrupted" until the AST routine is 
executed. The AST routine is executed even if the task is 
stopped or blocked. In that case, the task returns to its 
stopped or blocked state after the AST routine is 
executed, unless the AST routine or some external event 
unstops or unblocks the task in the meantime. 
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Figure 2-6 AST Mechanics 


The AST routine is a user written routine contained within 
the task. The user stack is set up in a special way by 
the Executive before the AST routine is entered, as shown 
in Figure 2-7. Notice that some ASTs have special words 
added to the stack. The AST routine may use these 
parameters to check on what caused the AST, and then take 
appropriate action. See section 2.3.4 on AST Service 
Routines in the RSX-11M/M-PLUS Executive Reference Manual 
for a discussion of the specific stack formats. 
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@ Finally, the AST routine uses the ASTXS$S Executive 
directive to "return" control to the main task code via 
the Executive. When the ASTXSS directive is invoked, the 


Executive assumes that the stack 


standard first four AST stack words. 


contains only the 
The user AST routine 


must clear any additional AST specific parameters off the 


stack before issuing this directive. 


© The Executive checks for any other ASTS which may have 
occurred while the AST routine was executing. Any such 
additional ASTs are queued up in an AST pending queue in a 


first-in-first-out order. These 


before the Executive "returns" to the 


and code. 


ASTs are also serviced 


"interrupted" state 


Note that the task's general purpose registers R@ through’ R5 


and SP are not saved. Therefore, if you use 
AST routine, you must save and restore them. 


For additional information on ASTs, see 


2.3.4 on ASTs and AST Service Routines 
Executive Reference Manual. 
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seats: AST SPECIFIC 
vewsp (7 PARAMETERS 
— K’ E W 
TASK’S DIRECTIVE STATUS WORD |] — an 
INCREASING PSW OF TASK PRIOR TO AST AST PARAMETERS 
mADRESSES PC OF TASK PRIOR TO AST ae 
OLD EVENT FLAG MASK WORD 
stack af 
(SP) a 


TK-7511 


Figure 2-7 Stack as Set Up by the Executive for ASTs 


Example 2-8 shows the use of ASTs. An AST routine is entered 
if-an abort request is made by either another task or an operator. 


The following notes are keyed to the example. 
@ Set up for AST on abort attempt. 
(2 | Loop until abort request comes in. 


@ Service routine entered on first abort request. For this 
AST, a nonprivileged task enters the routine only once and 
further ASTs are cancelled. If the task is built as a 
privileged task, the routine is entered each time an abort 
attempt comes in. See Appendix D for an explanation of 
privileged tasks. 


4 | There iS no need to set up the stack for the AST return, 
because there are no AST specific parameters (only the 
four words expected by the Executive are on the _ stack). 
The AST exit causes the Executive to transfer control to 
the task back in the main code where it was "interrupted." 


Another directive, SREXS, gives extended capabilities. An 
entry passed on the stack to the AST routine indicates whether the 
abort request came from a privileged or nonprivileged task or user 
and further, whether it came from an Abort Task directive or a DCL 
(or MCR) command. Each case can be handled differently. 
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1 +TITLE ASTEX 

is $+ 

3 > FILE ASTEX.MAC 

4 5 

a * This task sets ur @ Srecify Reauest Exit AST routine. 
é § It then sits in @ loor unmtil someone tries to abort 

7 $ ite At that roints it enters the AST routine and sends 
8 y out a messade. It won’t abort the first time. A second 
9 > ahort attemet will succeed because for this rarticular 
10 ’ AST» the first sabort AST cancels any further ahort 

11 s AST’s. 

12 $ 

13 s Assemble and task-hbuild instructions? 

14 3 

135 ; >MACKO/LIST ASTEX=LEB? C12 1IFPROGMACS/LIBRARY »—- 

16 3 ~sdev i CufdJASTEX 

17 ; SLINK/MAF ASTEX»LEt C1» 1 IFROGSUBS/LIBRARY 

18 3 

19 *MCALL SREAS$C es ASTX$S y External system macros 
20 *MCALL TYPFE ¢ External surrlied macros 
2i ; 
ae START? CLR RO § Error count 
Ra SREA$C REXAST ¥ Set ur Srecify Exit AST 
24 RCS ERR § Branch om dir error 
2 TYFE <ASTEX STARTING UF. WILL WORK UNTIL ABORTED. > 
26 + To some work. 
27 CLR R2 § Clear counter 
28 LOOQF ? INC R2 ¥ Increment counter 
29 ER OOF ~3 Loor back 

30 ’ Error code 
31 ERE AL? INC RO y Error count 
32 MOV $0SWeRi § Move [DSW for disrlay 
33 TOT i Trar and disrlay 

34 + Yresisters 

335 y AST service routine 

36 REXAST? TYFE “TRYING TO ABORT MEs EH?> ¢ Diselay 

37 TYPE “WE WON’T LET YOU THIS TIME!> ¢ message 
38 ASTX$S ¢ AST exit 
39 +ENT START 


Rum Session 


SINS ASTEX 
“RUN ASTEX 


" ASTEX STARTING UP. WILL WORK UNTIL ABORTED, 
ABORT/TASK ASTEX 


TRYING TO ABORT MEy EH? 
WE WON’T LET YOU THIS TIME! 
ABORT/TASK ASTEX 
LO257302 Task “ASTEX * terminated 
Aborted via directive or CLI 


Example 2-8 Using a Requested Exit AST 
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Example 2-9 shows the use of an AST routine with the Mark 
Time (MRKTS$) directive. The AST routine is entered after a 1@. 
second time period expires. The task starts the time period and 
then suspends itself until the 19. seconds go by. The AST 
routine, when entered, reSumes the task. Therefore, the task is 
unblocked and continues to execute when the AST routine exits. 
The "main" code then displays a message and exits. 


The following notes are keyed to the example. 


@ The Mark Time instructs the system to start the 19. 
second interval. The two specifies seconds. After that, 
the AST routine at ASTSRT is entered. The missing first 
argument is for an event flag, which would, if specified, 
be initially cleared and then set when the 1@. seconds 
expired. 


6 Task suspends itself. The AST routine is entered even 
though the task is suspended. 


3) The AST routine resumes the task. Otherwise, the task 
would return to a suspended state upon exit from the AST 
routine, 


@ This instruction cleans up the stack for the AST Exit 


directive. The extra word contains the event flag number 
of the event flag set, or zero (in this case) if none was 
specified. This word could be used to distinguish which 


MRKTS directive had expired in the case of several MRKTS 
directives, using different event flags but the same AST 
routine, 


@ After the task is resumed by the AST routine, it starts 
here. 


If a task uses the Mark Time directive to place a time limit 
on an operation, the Mark Time can be cancelled using the Cancel 
Mark Time directive if the operation completes before the time 
limit expires. 
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3 
he 


1 +TITLE MARK 
2 +IQENT 7/017 
3 *ENABL LC Y Enable lower case 
4 3+ 
3 § FILE MARK.MAC 
& ; 
7 § This Frogram issues a mark time for 10 seconds and 
8 § then stors itself. When the mark time exriresy an AST 
9 * routine is invoked which unstors the task. 
10 ; 
ii 5 Assemble and task-huild instructions? 
12 3 
13 3 MACRO/LIST LB?C1Ls LIPROGMACS/LIBRARY sdeviCufdIMARK 
14 $ LINK/MAF MARK ys LB C1» 1 JFROGSUBS/LINRKARY 
1S 3 
16 § Install and run instructions? 
1? 3 
18 3 The task must be installed under the mame MARK in 
19 r] order to rum correctly 
20 3- 
21 eMCALL EXIT#&S»sMRKTSC »¥ASTX$S + SPNIGS » RSUMSC 
22 ¥ System macros 
23 »*MCALL TYPE § Srecial surrlied macro 
24 
ao START: CLR RO § RO is used to identify 
26 y errors 
27 TYFE “=“MARK’ IS RUNNING ANTI WILL SUSPEND: 
28 TYPE “ITSELF UNTIL AST RESUMES IT> 
29 MRKT¢C 910-922 ASTSRT + Issue mark time 
30 RCS ERR1L § Branch on directive 
31 § error 
: SPNINSS § Susrend task. 
33 RCS ERR2 § Kranch on directive 
34 y error 
35 TYPE ““MARK’ IS RESUMED ANT WILL EXIT> 
36 EXITS s Exit 
37 ERR3? INC RO ¢ RO = 3 if error on 
38 y wumnstor 
39 ERR2? INC RO $ RO = 2 if error on 
40 > mark time 
Al ERR? INC RO ¢ RO = 1 if error on 
42 § stor 
43 MOV $0SWeR1 § Save SW 
44 IOT § Abort task and dumr 
45 y resisters 


Example 2-9 Using an AST in the Mark Time Directive 
(Sheet 1 of 2) 
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4S 5 
47 ; AST SERVICE ROUTINE 
48 ; 
49 ASTSRT? TYFE <AST ROUTINE EXECUTING ANDI WILL UNSTOF “’MARK’> 
O so RSUM$C MARK } Resume task 
o4 RCS ERRS | § Branch on directive 
Ka oe y error 
o3 + User must clean AST srecific values off the stack so 
54 § that the Exec gets control with stack as expected 
go + (with regular 4 AST words) 
O ss TST (SF)+ $ Clean off stack for 
a7 § AST return 
38 ASTX#$S § Return to main code 
wo? § through ast exit 
60 +ENTI START 


Rum Session 


INSTALL MARK 
“RUN MARK 


‘MARK’ ITS RUNNING ANID WILL SUSPEND 
ITSELF UNTIL AST RESUMES IT 
AST ROUTINE EXECUTING AND WILL UNSTOF ‘MARK?’ 
‘MARK’ IS RESUMED AND WILL EXIT 


Example 2-9 Using an AST in the Mark Time Directive 
(Sheet 2 of 2) 


Synchronous System Traps (SSTs) 


There is another kind of system trap available on the system, 
generally used if you wish to handle trap producing errors 
yourself, rather than have the Executive handle them. They are 
called Synchronous System Traps (or SSTs). They detect certain 
events which occur when program instructions are executed (e.g., 
odd address trapS and memory protect violations). They are 
synchronous because they always occur at the same point in the 
program, when a given trap-causing instruction is executed. 
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To set up for user coded SSTs, you must set up a vector table 
in a data area that contains a list of SST service routine 
addresses. Each entry in the table corresponds to a specific SST 
which may occur. A zero in an entry indicates that the Executive 
should handle that trap. Refer to Figure 2-8, which shows” the 
setup and use of an SST routine. The following comments are keyed 
to this figure. 


ay) At start-up, the task issues a SVTK$ or SVDBS directive, 
specifying the vector table address, which causes the 
Executive to record that address, setting up for user SST 
service routines. 


6 The Executive returns control to the task. 


(3) An instruction iS executed which causes ae trap. The 
Executive checks the SST vector table to see if the user 
has specified a routine to handle the trap. If one is 


specified, the Executive sets up the user’ stack and 
transfers control to the SST routine. If no SST routine 
is specified, the Executive aborts the task and displays 
an error message at TI:. 


@ once the task receives control again, it executes the SST 
routine as if in the main code. All system services are 
available to the task. To return to the main code, clean 
up the stack so it contains only the return PC and PSW, 
and execute an RTT or RTI instruction. 


6 The RTT or RTI instruction causes the PC and PSW to. be 
popped from the stack into the appropriate register, 
cauSing a return to the "interrupted" code. 


Note that the general purpose registers R@ through R5 and SP 


are not saved. Therefore, if you use these registers in an SST 
routine, you must save and restore them. 
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TASK CODE EXECUTIVE CODE 


DATA 
SST VECTOR TABLE SET UP POINTER 
AREA TO SST VECTOR TABLE 
SVTK$ DIRECTIVE 
MAIN 
CODE 
; BPT INSTRUCTION EXECUTIVE TRAP 
SERVICE ROUTINE 
SST 
SERVICE 
RTI OR RTT 
ROUTINE 


TK-7510 


Figure 2-8 SST Sequence 


Example 2-180 uses three SST service routines to handle _ BPT, 
IOT and memory protection violation traps in the user program. 
The following notes are keyed to this example. 


oc) Vector table containing the SST service routine addresses. 
See the documentation on SVTKS in Chapter 5 of the 
RSX-1L1M/M-PLUS Executive Reference Manual for the order of 
words in the table. 


2 Executive directive to permit the use of user SST service 
routines. You can also use SVDBS$ to trap to an external 
debugger (e.g., ODT) instead of to the user code. 


3) BPT causes a trap. The Executive checks the vector table; 
because a routine address is specified for BPTs, it sets 
up the stack and transfers control to location BPT. 

(4 | The BPT SST routine displays a message, then returns’ from 
trap, to line 28. 
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The CLR 1280800 causes a memory protect violation since the 
highest address used in this program is far below that 
(1627(8)). This causes another SST. 


On a Memory Protect Violation SST, the Executive passes 
three more words on the stack in addition to the PC and 
the PSW. The details on these words are discussed in 
section 26342 on SST Service Routines in the 


RSX-11M/M-PLUS Executive Reference Manual. 


We don't need the stack values in this routine, but we do 
need to pop them off the stack so that the RTI instruction 
works’ properly. The CMP and the _ TST are "dummy" 
instructions used to pop the three words off the stack. 


IOT causes another SST. 

In the IOT routine, we can alter the return PC (on the top 
of the stack), which changes the return point for the RTI 
to NEW. 

The TRAP instruction causes an SST for which there is no 


user specified routine. Therefore, the Executive aborts 
the task and displays a message at TI:. 
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*TITLE SST 
*IDENT /0O1/ 
eENABL LC ; 


FILE SST+MAC 


Enable lower case 


This task sets ur an SST vector table to handle SST’s 
for BFT»s ITOTs and odd address trars. It then executes 
instructions to cause these trars to occure In each 
SST routines 3 messade is disrelaeyed and then the task 
continues. Finallys a TRAP instruction is executed. 
Since mo user SST routine is srecified for TRAF» the 


Executive aborts the task. 


Assemble and task-build instructions? 


MACRO/LIST LE¢C1»LIPFROGMACS/LIBRARY »deviCufdIsst 
LINK/MAF SST»LBi Cl» 1LIPROGSUBS/LIBRARY 


*MCALL SVTRECYEXITSS ; 
*MCALL TYPE 3 


? 
VIABLE? «WORD O»MPTVIOs BPTs TOT 


9 


START: SVTK$C VTABLEs4 


External system macros 
External suprelied macro 


+ SST vector table 


Have Executive set ur 
SST table 


g 
¥ 
RPT s BET instruction 
CLR 120000 $ Clear location 120000» 
+ Causing & memory 
§ Frotect violation 
IOT § TOT instruction 
EXIT$S s Exit 
NEW? TRAF § TRAP instruction 
bd 
§ SST routines 
9 
MPTVIO’ TYPE “MEMORY FROTECT VIOLATION CAUGHT= ¢ Ture 
5 messase 
CMF (SFO +49 (SP) + § Clean off three 
TST (SP)+ + $recific stack words 
§ for memory rrotect SST 
RTI § Return from trar 
BET? TYPE “<BFT CAUGHT? § Tyre messase 
RTI + Return from trae 
IOT? TYFE “<IOT CAUGHT: i’ Tyre message 
MOV #NEWs (SF) * Chanse FC on stack so 
§ return from trar 
§ returns to NEW 
RTI + Return from trar 
eENTI START 


Example 2-18 Using SSTs (Sheet 1 of 2) 
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Rum Session 


>RUN SST 
BET CAUGHT 
MEMORY PROTECT VIOLATION CAUGHT 
LOT CAUGHT 
$4307250 Task "TT11 " terminated 
TRAF execution 
RO=O001573 
Ri=Q0001L2 
R22000000 
R3=L4oO312 
R4=144000 
RS=000000 
SF=O01L254 
FC=O001312 
FS=170000 


Example 2-1@ Using SSTs (Sheet 2 of 2) 


Now do the tests/exercises' for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either in that book or in 
on-line files, under UFD [2902,2]. 


You will need the program READF.MAC to do question 1. It 
should be available on-line (probably under UFD [2@2,1]). In case 
it is not available on-line, the source code is listed in Appendix 
G. 


If you think that you have mastered the material, ask your 
course administrator to record your’ progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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USING THE QIO DIRECTIVE 


INTRODUCTION 


All input/output under RSX-11M is performed using the QIO 
directive. In this module, you will learn how to use the QIO 
directive, concentrating on its use for input/output to a 
terminal. 


Sa 


OBJECTIVES 


To use the QIO directive to perform I/O to a device that 
is not file-structured (e.g., a terminal) 


To choose either synchronous or asynchronous I/O as_ the 
most effective method for a given application 


To perform complete error checking upon I/O completion 


To use formatting routines from the system subroutine 
library to improve the readability of output data. 


RESOURCES 


RSX-11M/M-PLUS Executive Reference Manual, specific 
directives in Chapter 5 


RSX-1L1M/M-PLUS I/0 Driver's Reference Manual, Chapters 1, 
2 and 3 


IAS/RSX-11 System Library Routines Reference Manual, Chap- 
ter 6 
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OVERVIEW OF QIO DIRECTIVES 


All I/O operations under RSX-11M are performed using QIO 
directives. The QIO directive causes an I/O request to be passed 
to the appropriate service routine. The service routine is either 
a device driver or a system task called an ancillary control 
processor (ACP). There is a device driver for each device type on 
the system. There are three ACP's provided: F1lACP for FILES-1l 
structured disks, MTAACP for ANSI magtape, and NETACP for DECNET. 


The I/O packet is placed in an I/0 queue for the- service 
routine. The packets are queued up in order according to the 
priority of the issuing tasks. If there are multiple requests at 
a given priority, those requests are queued first-in-first-out 
(FIFO). The QIO directive does not perform the I/0 operation 
itself, but simply queues the request to the appropriate service 
routine, which performs the actual I/O transfer. After the I/O 
request has been queued, the Executive returns control to the 
issuing task, unless the task requests the Executive to place’ the 
task in a Wait For state until the I/O transfer completes. 


PERFORMING I/O 


QIO directives are generally used only for I/0 on _  non-file 
Structured devices such as_ terminals. For file I/O, the File 
Control Services (FCS) or Record Management Services (RMS) are 
used, which in turn issue the appropriate QIOs for you. 


When uSing QIOs, you need to specify which I/0 operation 
(e.g., Read Virtual Block or Write Virtual Block) is to be 
performed by means of an I/O function code. Specify the device by 
means of the logical unit number (LUN). To specify additional 
information about the I/0 operation (e.g., what buffer to write 
and how many characters), use an I/O Parameter List (IOPL). All 
of this information is passed to the Executive through parameters 
in the Directive Parameter Block (DPB), as it is with all 
Executive directives. 
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I/O FUNCTIONS 


Each device type has its own set of legal I/O functions. 
Certain functions are called standard or common, Since they are 
available on all devices. The seven standard I/0 functions are 
listed in Table 3-1. Logical block transfers (Read Logical Block 
and Write Logical Block) can usually be performed for any device. 
For file-structured devices, virtual block transfers can be 
performed only if a file is open on the device. If Virtual Block 
I/O is requested for a device which is not file-structured, such 
aS a terminal, it is converted to logical block I/0 for _ you. 
Devices may have additional device specific functions, such as 
read no echo at a terminal. Each function requires its own set of 
parameters, which are specified in an I/O parameter list. 


Table 3-1 Common (ence I/O Function Codes 


ee sure 
Ee 


_ 


| 


eo. = 
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Logical Unit Numbers (LUN) 


The device for an I/O operation is specified by means of a 
logical unit number. The correspondence between logical unit 
numbers and physical devices is made initially at task-build time. 


The default LUN assignments set up by the Task Builder are as 
follows: 


LUN #1 - SY: 
LUN #2 - SY: 
LUN #3 - SY: 
LUN #4 - SY: 
LUN #5 - TI: 
LUN #6 —- CL: 


These default assignments may be overridden at  task-build 
time by using the ASG option. Additional LUNs can be created (up 
to a maximum of 25@(18)) by using the UNITS option. 


Once a task is installed, an operator can check the _ LUN 
assignments for the task by using the DCL SHOW LOGICAL UNITS 
command (LUN in MCR). The assignments can be changed by an 
operator using the DCL ASSIGN/TASK command (REA in MCR). The LUN 
assignments can also be checked at run time using the Get LUN 
directive (GLUN$), and changed using the Assign LUN directive 
(ALUNS). 


Synchronous and Asynchronous I/O 


There are two kinds of I/O, synchronous I/O and asynchronous 
I/O. With synchronous E70; the Executive provides all 
synchronization. With asynchronous’ I/O, you must provide 
synchronization regarding the completion of the I/O operation 
itself. 


When a task issues a synchronous I/O request, it doesn't get 
control back from the Executive until after: 


1. The I/O packet is queued, and 


2. The I/O operation (the transfer performed by the service 
routine) itself is completed. 


In other words, the synchronous I/O request asks the Executive to 
queue the I/O packet and then place the task in a Wait For state, 
to wait until the specified event flag is set, signifying that the 
actual I/O operaton is complete. 
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Figure 3-1 shows the flow of instructions during the 
‘processing of a QIO directive. The task does not execute the 
instruction following the QIO directive until after the MI/0 
transfer itself has completed. Figure 3-2 shows a time diagram 
illustrating the same I/O operation. Note that once the QIO 
directive is executed at step 1, the task doesn't execute again 
until step 8, after the transfer has completed. The system 
handles all synchronization with synchronous I/O. Use the QIOWS 
directive to invoke this type of I/O. 


Commentary to Figures 3-1 and 3-2: 

User task executes QIO and Wait For directives. 
Executive queues the I/O request. 

Executive calls the driver. 

Driver begins the I/O transfer. 

Driver handles the I/O transfer as necessary. 


I/O transfer completes. 


Driver finishes its work and notifies the task that the 
I/O is completed. 


User task continues. 
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EXECUTIVE 


QIO DIRECTIVE 
ROUTINE 


USER TASK 


1/0 QUEUE 


TK-7507 


Figure 3-1 Execution of a Synchronous I/O Request 


USER TASK 


QIO DIRECTIVE 


DRIVER 


1/0 TRANSFER 


TIME 


TK-7509 


Figure 3-2 Events in Synchronous I/0 
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With asynchronous I/O, the Executive still queues the I/O 
request. When a task issues an asynchronous I/O request, the 
Executive passes control back to the task immediately after the 
I/O packet is queued to the driver. You must provide 
synchronization concerning the completion of the actual I/0 
transfer. This could occur at various times, depending on such 
factors as how many other I/O packets are ahead of this one in the 
driver's I/O queue, and the speed of the device itself. The task 
executes in parallel with the I/O request. 


In Figure 3-3, the instruction after the QIO request is 
executed after the I/0 packet is queued (and the driver has 
started the transfer), not after the I/O transfer completes. The 
task continues executing unless it chooses to wait. Figure 3-4 
shows a time diagram illustrating asynchronous I/0. 


Note that after the QIO directive is executed at step 1, the 
task begins executing again at step 5. In this example, the task 
waits for the I/O transfer to complete at step 5a . If you~ use 
asynchronous I/0, you must provide any synchronization yourself, 
using event flags, asynchronous system traps, or both. The task 
shown in Figures 3-3 and 3-4 uses a Wait For Single Event Flag 
directive at step 5a. Use the directive QIOS to invoke this type 
of I/O. 


The advantage of asynchronous I/O is that a task can continue 
processing in parallel with the I/O transfer. For example, you 
can perform computations while waiting for a read or write to 
complete. Of course, if you need the information from the read 
before you can do anything else, it is better to use synchronous 
I/O. 
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Commentary to Figures 3-3 and 3-4: 


User task executes the QIO directive. 
Executive queues the I/O request. 
Executive calls the driver. 


Driver begins the I/0 transfer; Executive passes’ control 
back to the user task. 


Driver handles the I/O transfer as necessary. User task 
executes in parallel with the I/0 transfer. 


a. User task waits for the I/O operation to complete. 
I/O transfer completes. 


Driver finishes up and the Executive notifies the task 
that I/O is completed. 


User task continues. 
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EXECUTIVE 


QIO DIRECTIVE 
ROUTINE 


USER TASK 


1/0 QUEUE 


TK-7518 


Figure 3-3 Execution of an Asynchronous I/0 Request 


USER TASK 
QIO DIRECTIVE 
DRIVER 


I/O TRANSFER 


TIME 


TK-7513 


Figure 3-4 Events in Asynchronous I/O 
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MAKING THE I/O REQUEST 


Specify the following information in the QIO$ or QIOWS call 
when requesting I/O. 


e Synchronous or asynchronous I/0, by using the appropriate 
directive. 


e The I/O function to be performed. 
e The LUN to be used for the I/0 operation. 


e An event flag number, if any, to be used for 
synchronization. This is required for synchronous I/O. 


e The address of an I/O Status Block (IOSB) - two words” set 
aside with .BLKW or .BLKB assembler directives. The IOSB 
is used to pass status and other information about the I/0 
operation back to the task. 


e The address of an AST routine, if transfer to an AST 
routine is desired upon completion of the I/O transfer. 


e The I/O parameter list (up to six words) which specifies 
information for the particular device and for the 
particular I/O function requested. 


Table 3-2 shows the I/O parameter list arguments which are 
needed for each of the standard I/O functions with the full-duplex 
terminal driver. Table 2-3 (in section 2.3 on the QIO Macro) in 
the RSX-11M/M-PLUS I/O Driver's Reference Manual lists these 
standard functions and the other device-specific functions 
available with the full-duplex terminal driver. The 
device-specific functions will be discussed further, later in this 
module. If your RSX-11M system has’ the half-duplex terminal 
driver, Table 3-3 in section 3.3 on the QIO Macro lists’ the 
functions available with that driver. For other devices, there is 
a corresponding table in the appropriate chapter of the manual. 
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I/O Parameter List for Standard I/O Functions 


Table 3-2 
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Error Checking and the I/O Status Block 


There are two kinds of errors which can be produced by QIO 
directives, directive errors and I/O errors. The various 
directive and I/O status codes and their meanings are listed in 
Appendix B of the RSX-11M/M-PLUS I/O Driver's Reference Manual and 
also in the RSX-11M Mini-Reference. 


Directive errors occur because of errors in processing’ the 
directive and getting the I/0 packet queued up to the device 
driver. As with all directives, directive errors are indicated by 
a negative value in the DSW and the carry bit set upon return to 
the task code. Success is indicated by a _ positive value 
(typically +1) in the DSW and clearing of the carry bit. 
Therefore, the directive status indicates the success or failure 
of the attempt to queue the I/0O packet. Check for directive 
errors immediately upon return after the QIO directive is issued. 


Upon completion of the I/O transfer itself, the Executive 
returns status information about the I/O transfer to the I/O 
Status Block, laid out as follows: 


Device Dependent I/O Status 


Actual Number of Bytes Transferred 


NOTE 
The low-order byte of the first word of the 
I/O Status Block contains the I/0 status 
code. This is a byte value, not a word 
value. A positive I/O status code (usually 


+1 = IS.SUC) indicates’ success. Again, 
negative values indicate various error 
conditions. The second word of the I/O 


Status block indicates the number of bytes 
actually transferred, which is significant in 
the case of any read or a write which ends 
after only some of the data is’ transferred. 
The device dependent byte usually contains 
information which is device dependent. For 
example, for a read from a terminal, it 
contains the character which was typed as a 
terminating character (<RET>, CTRL/Z, <ESC>, 
etc.). 
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The I/O status byte should be checked only after the I/0 
transfer completes. For synchronous I/0, the I/O status should be 
checked right after checking the DSW, since the I/O transfer 
itself also completes before control is returned to you. For 
asynchronous I/0, on the other hand, the I/0 status should be 
checked when the task is notified by the Executive that the 
transfer is complete. Synchronization is discussed in the section 
that follows, after an example of synchronous I/O. 
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THE QIO DIRECTIVES 


Synchronous I/O 
The format of the QIOWS call is: 


QIOWS ifn,lun,efn,pri,iosb,ast,iopl 


where 

ifn - I/O function code 

lun - Logical unit number 

efn - Event flag number (required for synchronous I/0) 
pri - Priority (not used) 

iosb - I/O status block address 

ast - AST routine address 


iopl - I/O parameter list 
Example using the $S form: 


~-MCALL QIOWSS 


BUFF: .ASCII /HERE IS THE MESSAGE/ 
LBUFF: =.-BUFF 

- EVEN 
IOSB: .BLKW 2 


QIOWSS #IO.WVB,#5,#1,,#I0SB,,<#BUFF,#LBUFF, #49> 


Explanation of QIO arguments: 


Write Virtual Block 
LUN 5 (TI:) 
Event flag #1 
Priority (always ignored) 
I/O status block address = IOSB 
AST routine address (none specified) 
I/O parameter list 
Input buffer address = BUFF 
Buffer length = LBUFF 
Vertical format control = 48(8) for single space 
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Once again, the $, $C, or $S form of the directive may be 
used. An event flag must be specified for synchronous I/O. If 
one iS not specified, the I/0 request is handled as an 
asynchronous I/O request. The priority is included to allow 
compatibility with RSX-11D. It is not used in RSX-11M. 


ASTs are not generally used for synchronous I/0, because’ the 
Executive performs all synchronization for you. The I/O parameter 
list is a single directive parameter. Therefore, the list is 
enclosed in angle brackets, with the elements separated by commas. 
In fact, six words are always placed in the DPB for the I/O 
parameter list, whether or not all six words are specified. 


Example 3-1 shows the use of synchronous QIOS. The following 
notes are keyed to the example. 


1) As with other directives, the macro names~ must be 
specified in a .MCALL statement. Note that in this 
example, we use both the $C form and the $S form of the 
QIOWS directive. 


6 ~The two-word I/O status block for return of I/O status. 


The buffer into which the data will be read, and also from 
which the data will be displayed. 


@ R4 is used to indicate whether a QIO error is a directive 
error or anI/O error. A value of zero indicates that a 
directive error occurred (and that R3 will contain the DSW 
value). A value of -1(177777(8)) indicates that an I/O 
error occurred (and that R3 will contain the I/O status 
byte). 


@ Issue the read request. We are uSing LUN 5, event flag l, 
and IOSB is the label of the IOSB. The I/O parameter list 
is set up aS a single parameter (hence the need for’ the 
angle brackets (< and >)). It specifies BUFF, the 
address of the buffer for the characters read and 8@., the 
maximum number of characters to read. If input is 
terminated with a terminating character, such as a 
carriage return, before 8@ characters are typed in, the 
number of characters actually read will be returned in the 
second word of the _ IOSB. Input will be terminated 
automatically after the 8@th character, if 8@ characters 
are typed. In that case, 8@ will be returned as the 
number of characters read. 
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Check for directive error - indicating a failure in 
queueing the I/O packet. 


With synchronous I/0, we don't get control again until 
after the I/O operation has completed, so also check the 
I/O status. A value less than zero indicates an error in 
the I/O transfer. 


Get the count of characters typed in from the second word 
of the IOSB. We will only check on and convert that many 
characters. 


Check each character to see if it is in the range ASCII A 
to ASCII Z. If so, convert to lowercase by adding 32(198) 
= 49(8) to that value, or else continue. 


Write out the buffer BUFF, which has the converted 
message. This is a Write Virtual Block. We use the $S 
form instead of the $C form because we don't know how many 
characters to write until run time. The $ form would also 
work. Notice the difference in the format of the 
arguments for the $S form compared to the $C form. Note 
also that in the $S form, the lack of a '#' sign in IOSB + 
2 means get the contents of that location, specifically 
the number of characters to write out. The third argument 
of the I/O parameter list, #48, is for vertical format 
control. Single linefeed before writing the characters is 
indicated by #48, or ASCII space. 


Check for any directive or I/O errors. 


See note 4. R5 is the directive counter, which will be 
one for the first QIO and two for the second QIO. We need 
to distinguish directive errors from I/O errors. In this 
example, we use R4 to distinguish the two type of errors. 
Zero in R4 means a directive error, and -1 (or 177777(8) 
in two's complement) in R4 indicates an I/O error. For 
directive errors, the DSW is’ placed in  R3; for I/0 
errors, the I/O status byte is placed in R3. 
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The list of all error codes appears in Appendix B of the 
RSX-11M/M-PLUS I/O Drivers Reference Manual and in the RSX-11M 
Mini-Reference Manual. Of course, this simple error handling will 
normally be replaced with a text error message and the error code. 
You will learn how this is done later in the module. 


NOTE 

Although both virtual block and logical block 
operations are permitted to a terminal, it is 
safer to use virtual block operations. If 
the I/0 is actually performed at a terminal, 
the virtual block request gets converted by 
the Executive to a logical block request. 
If, for example, logical block writes are 
used and someone reassigns the LUN to a disk, 
the write may overwrite a block on the disk. 
If, on the other hand, write virtual blocks 
are used and someone reassigns the LUN to a 
disk, the write will only be allowed if a 
file is open on the disk. The write will 
fail in most cases if the program is writing 
to a terminal. 
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sTITLE SYNCHRQ 


»ITENT /0O17 

*ENABL LC + Enable lower case 
+ 
FILE SYNCHQ.MAC 


S> “hr Wy Sd “ar “Sh S> “GP 


| MCALL QIOWSC »QTOWSS rEXITSS 


LOSE? BLAW 
RUFF $ + BLAKE 


START$ CLEA 
CLA 


QTOWSC TO.RVErS+1»»TOSE 


BCS 
TSTE 
BLT 
MOV 


CLA 
LOOF CMF ER 
BLT 


CMFR 
BGT 


This task reads a line of text from the terminal» 
converts all 
erints the converted messade hack at the terminal. It 
wees synchronous QIO directives. 


urPrer case charecters to lower casey and 


> External system 
> macros 

= y I/O Status Block 

80. § Text buffer 

RS Error Courmt 

R4 Error indicator ~- 0 


3 

> means directive error 
, (iISW im R3)» mest 

§ means I/O error 

y (1/0 status im RS) 

yes i BUFFsS0.> 3 Issue 


a 


; reac 


ERR1 > Branch on dir error 

[OSE § Check for I/0 error 

ERRIA > Branch om I/0 error 

IOSK+2sRK0 > Get count af characters 
§ tured in 

Ri > Offset into huffer to 
y character 

BUFF CRI) »t°A + Check for urrer case 
y ASCII character 

NEXT y Branch if below ranse 

BUFF ORL) 9 #°Z 

NEXT > Branch if above range 


i Here if urrer casey move to resister R2 and convert 


MOVE 
An 
MOVE 
NEXT? INC 


SOR 


Move to resister 


BUFF CRI} sR2 3 
#32. 9R2 § Convert to lower case 
R29 BUFF CRI) y Rerlace in message 
Ri y Increment offset into 
y huffer to mext char 
RO» LOOF y tecrement count of 
y 


characters left to check 


QIOWSS #IO.WVEs #5 #1» o FLOSRs » SBUFF e TLOSR+2 9 #402 


Example 3-1 


+ Write text 


Synchronous I/O (Sheet 1] of 2?) 
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48 BCS ERR2 § Branch on dir error 

49 TSTE IOSB ¢ Check for I/0 error 

50 BLT ERR2A § Branch on I/0 error 

S1 EXIT&S § Exit 

52 3 

33 §’ Error code 

u4 ; 

a be ERR2A? INC RS + Ur error count - 2nd Qro 
36 ERRIAS INC RS 3 ~ Ist Qo 
Oo? ; MOVE IOSKsRS ¢y I/O error. I/0 status 

358 + to RB. 

99 EC R4 §’ Nesative value in R4 

460 > means I/0 error 

61 IOT. 9 Trar and disrlay 

62 y fesisters 

63 ERR? 3 INC RS > Ur error count ~ 2nd QTO 
64 ERR? INC RS 3 -~ Ist QI0 
65 MOV $UISWeRS > Lirective error. [ISW 

66 § to R3: leave R4=0,. 

67 IOT > Trar and disrlay 

68 > resisters 

6&9 +END START 

Run Session 

=>RUN SYNCHRQ 


ABCUTEFGHI Jk Ii mnorerstuvwxy2z12345é678L0 IN 
ahbedefshidklmnorarstuvaxge1234S5678LI\ 


Example 3-1 Synchronous I/0 (Sheet 2 of 2) 
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Asynchronous I/O 


The format of the QIOS call is: 


QIOS ifn,lun,efn,pri,iosb,ast,iopl 
where 
ifn - I/O function code 
lun - Logical unit number 
efn - Event flag number 
pri - Priority (not used) 
iosb - I/O status block address 
ast - AST routine address 


iopl I/O parameter list (up to six words) 


Example using the $C form: 


~-MCALL QIOSC 


IBUF: .BLKB 80. 
IOSB: - BLKW 2 


QIOo$c I0O.RVB,5,1,,I0SB,,<IBUF,80.> 


Explanation of QIO arguments: 


Read Virtual Block 
LUN 5 (TI:) 
Event flag l 
Priority (ignored) 
I/O status block address = IOSB 
AST routine address (not used here) 
I/O parameter list 
Buffer address 
Buffer length 


IBUF 
80. 
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Synchronization With Asynchronous |/O 


As mentioned earlier, event flags and asynchronous’ system 
traps may be used for’ synchronization. If an event flag is 
specified, the Executive clears the event flag when the I/O packet 
is queued and sets the flag again when the I/O transfer completes. 
This happens with both synchronous and asynchronous I/0, if an 
event flag is specified. With asynchronous I/O, the task can 
specify a flag and use it for synchronization using one of the 
following techniques. 


1. Do some work, then wait for the flag to be set. 


2. Work the entire time, periodically checking the flag until 
it is set. 


Another possible technique for synchronization is to use ASTs 
(discussed in Chapter 2). The following techniques might be used 
with ASTs, after specifying an AST routine address in the QIO$ 
directive. 


1. "Main" task does some work, then suspends or stops itself. 
AST routine resumes or unstops the task. 


2. "Main" task works the entire time, periodically checking a 
cleared event flag or a cleared byte in a local data area. 
AST routine sets the flag or sets the byte to a nonzero 
value, thus notifying the "main" task that the I/0 
operation has completed. If an event flag is used, it 
will typically be different from the flag specified in the 
asynchronous I/O request. 


A third technique which can be used is to monitor’ the 
contents of the I/O status byte of the I/O status block. The 
complete I/O status block is cleared when the I/0 request is 
queued to the driver. Later, it is filled in when the I/0 
transfer completes. Therefore, the user task can periodically 
check the contents of the I/O status byte for a nonzero value. 
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Example 3-2 demonstrates the use of asynchronous I/0 to 
perform the same function performed in Example 3-1. This task can 
do some work in parallel with the I/O transfer. The following 
notes are keyed to the example. 


Here we use QIOSC and QIOSS instead of QIOWSC and QIOWSS. 
WTSESC is a Wait for Single Event Flag directive, used to 
synchronize the I/0 operation. 


A work buffer to be filled with values while the I/0 
transfer is going on. 


Issue the read. QIOSC instead of QIOWSC. All arguments 
are the same. If ASTsS were used for synchronization, an 
AST address would be specified. The Executive will clear 
Event Flag 1 when the I/O packet is queued and set it when 
the I/O operation completes. 


Check again immediately for directive errors. Here, you 
are checking for an error in queueing the I/O packet. 


While the I/O transfer itself takes place, you can do some 
work. Here fill the “array” at K with the values 64., 
L 2S 6. gp asewcy 640. 


When you are finished with your work, enter a Wait For 
state until the event flag specified in the QIOS directive 
is set. It will be set when the I/O operation completes. 


Now that the I/O operation is finished, check for I/O 
errors. 


After converting the message, issue the write. 


This time, wait for the flag to be set immediately after 
checking the directive status. You could do some more 
work here. If you choose to wait, it is simpler and more 
efficient to use synchronous I/O (QIOWS). Synchronous I/0 
is more efficient because you perform both functions (QIOS$ 
and WTSES$) in just one Executive directive call. 


Still use the error count to indicate the directive 


number. Since there are now extra directives (the WTSEs), 
adjust the counts accordingly. 
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*TITLE ASYNCA 
+ITENT /O17 
+ENABL LEC ¢ Enable lower case 


FILE ASYNCQ.MAC 


This task reads a line of text from the terminals 
converts all urrer case cheracters to lower casey and 
Frints the canverted message back at the terminal. It 
uses asynchronous QLOs usins wait for event flad for 
synchronization. 


*MCALL QLOSC*QTOSSesEXITSSeWTSESC ¢ External 


> system macros 


SE: *BLAW 4 y I/O Status Block. 
FF 3 +BLAE 80, * Text buffer 
+ BLKW 10. ’ Array to fill while 
§ waitins for I/70 
ART? CLR RS §y Error Count 
CLA R4 ’ Error indicator? 0 
$s means directive errors 
y -l means I/0 error 
QIOsC IO.RVBySyly»TOSBs s BUFF 280.9402 ¢ Issue 
y read 
ECS ERR § Branch om dir error 
Now do some work. 
CLR RO ¢§ Offset into array K 
MOV #64. 9R1 § Value to elece in array 
ACE? MOV RivyK CRO) § Flace value in array 
ALi #2°RO 5 Foint to next element 
> in kK 
CMF ROs #20, s AL the end? 
BHI WAIT i Branch if done 
ALT #454.9R1 § Comrute mext value 
ER PLACE § Flace it in the array 
Now wait for I/0 oreration to comrlete 
IT? WTISE$C 1 § Wait for I70 to 
— comrlete 
RCS ERR2 + Check for dir error 
TSTE IOSE § Check for I/0 error 
RLT ERRIA 5 Branch om I/0 error 
MOV IOSE+2%RO § Get count of characters 
§ tyred in 
CLR Ri s Offset into buffer to 
§ cheracter 


Example 3-2 Asynchronous I/O Using Event Flags 


for Synchronization (Sheet 1 of 2) 
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48 
49 
30 
ea 
S2 
33 
34 


babe 


56 
a7 
38 
hed 
60 
61 
62 
63 
64 
65 
66 
6? 
68 
69 
70 
71 
72 
73 
74 
735 
76 
7? 
78 
79 
80 
81 
B2 
83 
B4 
85 
B46 
87 


Fun 


>RUN 


LOOF ? 


a 


NEXT? 


¢ Could 


$ Error 
ERR3A? 


ERRIA’ 


ERR4 } 
ERRS $ 
ERR2? 
ERR1¢ 


Session 


ASYNCQ 


USING 


> Here if urrer 


THE QIO DIRECTIVE 


#IO.WVBy €5°41+°#1T0SBe » <# BUFF y TOSK+2 2 $402 
Write text 


CMF E BUFF CRI)» #°A 
BLT NEXT 
CMF E BUFF CRI) »#°2Z 
RGT NEXT 
Casey 
MOVE RUFF CRI)» Re 
AQT $32. 9R2 
MOVE R2»BUFF CRI) 
INC Ri 
SOR RO»LOOF 
QTOss 
RCS ERRS 
do some more work 
WTSE#$C 1 
BCS ERR4 
TSTR IOSE 
BLT ERRSA 
EXITSS 
code 
INC RS 
INC RS 
INC RS 
DEC R4 
MOVE TOSHs» RS 
LOT 
INC RS 
INC RS 
INC RS 
INC RS 
MOV $OSWye RS 
IOT 
*END START 


a 
9 


a 


Sr G> “Sr “er “Se *@: 


a 


¥ 


a 


¥ 


here too 


e> @> S> SP Sr HD 


Sh “AP WS Sh Wh WP HP “Gr “Gh Wd “> “Ge “Ch “he “EP SEP 


Check for 


UPPar Case 


ASCII character 


Branch if 


Branch if 


below ranse 


above ranse 


move to resister R2 and convert 


Move to resister 
Convert to lower case 


Rerelace in 


Increment 


mMEeSsadte 
offset into 


buffer to nmext char 


Necrement 


Branch on 


char caunt 


dir error 


Wait for I/0 to 


comrlete 
Branch on 
Check for 
Rranch on 
Exit 


RS=3s 2nd 


lst 


(S=1 5 


dir error 
I/0 error 
I/Q error 


QIO 


Qro 


Make R4 nesative to 


indicate 


I/O error 


I/O status to RS 
Trae and disrlay 


resisters 
RS=4% 2nd Wait For 
RS=3» 2nd QIoO 
RS=2% Ist Wait For 
RS=1y ist QI0 
Tlirective error. [SW 
ta RS» leave R4=0, 


Trae and diselay 


resisters 


abecdefehK JHKIJHKHFRTEWawryusiuroZCVevavenbMBNM? (8534243 "3 / 
ahbedefshk Jhk Jnkhf rtewawryuygiurozgevevbvenbmbnm? (8534243 " 3% 


Example 3-2 
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Asynchronous I/0 Using Event Flags 


USING THE QIO DIRECTIVE 


Example 3-3 shows the use of ASTs for synchronization. In 
addition, it shows the use of some supplied macros for generating 
error reports. These macros are documented in Appendix A of this 


course. 


The following notes are keyed to the example. 


This is the text for the messages to be written. The 
LEN=.-MES lets the assembler calculate the length of the 
message for you. A similar technique is used for’ the 
other messages. 


The ASCII text may contain an odd number of characters. 


The .EVEN assembler directive assures that your first 
executable instruction is an even word boundary. 


Issue the write request. The AST routine address is 
specified. Also specify the address of the buffer, MES, 
and its length LEN. You can use the $C form of the 
directive because all arguments are known at assembly 
time. 


Suspend until the AST routine is activated: upon I/0 
completion. Normally some other processing would be done 
here, in parallel with the I/0O operation. 


The Executive passes control to the AST routine when the 
I/O transfer completes. First check the I/O status. You 
do that here instead of in the main code because you will 
be issuing another write which will overwrite the IOSB. 
The I/O status check could otherwise be checked in the 
main code after the task is resumed. 


_Write out a message so the operator knows you are in the 


AST routine. This time you use synchronous I/0, since you 
aren't planning to do any work while the I/O transfer 
takes place. Again, check for errors. 


Resume the task so it will be ready to run upon exit from 
the AST routine. ' 


Pop the extra word off the stack (this AST is entered with 
five words on the stack instead of the standard four). 
Then use the ASTXS directive to exit the AST routine via 
the Executive. 


Check for directive errors on the SPNDS. It's possible 
that you never suspended yourself. 
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Write another message synchronously, check for errors, and 
then exit. 


The DIRERR and IOERR macros generate error messages’ for 


you. DIRERR generates a message with the following 
format. 


DIRECTIVE ERROR 
<user message> 
DSW = <value> (in signed decimal) 


IOERR generates a message of the following format: 


I/O ERROR 

<user message> 

I/O STATUS BLOCK = <hb>,<lb>/<2nd word> 
(in signed decimal) 


hb is the high byte of the first word. 
lb is the low byte of the first word. 


Each of these macros then causes the task to exit. Later 
in this module you will learn how to generate such 
messages yourself. 


117 


USING THE QIO DIRECTIVE 


1 +TITLE QIO0AST 

2 +IDENT /O1/7 

3 *+ENABL LC § Enable lower case 

4 3+ 

3 y FILE QIOAST.MAC 

6 5 

7 * This rrosgram issues a QIO and then susrends itself. 
8 ¢y When the I/0 oreration comeletess an AST routine is 
9 § invoked which resumes the task. 

10 5 

11 § Assemble and task-build instructions? 

12 ; 

13 ; MACRO/LIST LE? C1ls1IFROGMACS/LIBRARY sdevi lufdIQrIoAsre 
14 § LINK/MAF QIOAST»sLEtCi sy lLIFROGSUBS/LIBRARY 

15 5 

16 § Install and run instructions! Install] the task so that 
17 ¢s the Resume directive works rrorerly. 

18 3 . 

19 eMCALL EXIT#S sQTO&CrQIOWSCrASTX$S ¢ Sustem 
20 *MCALL SPNISS +s RSUMEC 5 macros 
21 *MCALL IOERRysRIRERR > Surrelied macros 
oa IOSB? +» BLKW 2 s I/0 status block 
23 MES3 *ASCII /’*QIOAST’ IS STARTING/ ¢$ Startur messase 
24 LEN = +~MES 

25 MES? *ASCITI /*‘QTOAST’ HAS BEEN RESUMED ANT WILL/ 

@ 26 eASCII / NOW EXIT > Resumed messasde 

27 LENI a »~MES1I 

28 MES33 *ASCII /ASTRT IS EXECUTING AND WILL NOW/ 

29 *ASCII / RESUME QIOAST/ + AST message 

30 LENS a 27 MESS 

3i +E VEN 


@22 START! QIO$C LO. WUBy Sri *1OSByASTRT» <MESrLEN» 40> 


33 ¢ Issue write 

34 RCS ERR 1 § Branch on dir error 
O. 35 SFND$S } Suspend self 

36 RCS ERR2 § Branch on dir error 
© 37 QTIOWSC TO WVRes Seley TOSBs siMESLeLENL 40> ¢ Issue 

38 5 write 

39 RCS ERRS § Kranch om dir error 

40 TSTE IOSE § Check for I/0 error 

41 BLT ERRSA > Branch om I/0 error 

42 EXIT#S > Exit 

43 § Main code error handling: using surrelied macros 


44 ERR1$ QIRERR <ERROR ON 1ST QIO BY QIOAST> 

45 ERRIA’ IOERR #IOSB»yERROR ON 1ST QIO BY QIOAST> 
d 46 ERR23 QIRERR “ERROR ON SUSPENTI 

47 ERRS$ QDIRERR <ERROR ON 2ND QIO BY QIOQAST> 

48 ERR3A3 IOERR #TOSER»<ERROR ON 2NT QIO BY QIOAST> 


Example 3-3 Asynchronous I/O Using an AST for Synchronization 
(Sheet 1 of 2) 
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49 3 

50 > AST service routine ~- entered when the ist QIO by the 

S1 $ main code comrletes 

32 ; 

33 ASTRT? TSTE IOSE § check I/0 status on 
Oo}: $ 1/0 operation 

35 BLT ERR1IA § Branch om I/O error 
6) HiT.) QTIOWSC IO.WVBsSeissTOSBs s=MESS»sLENS»40> §¢ Issue 

37 + write 

38 RCS ERR4 § Branch on dir error 

a? TSTE IOSE ¥ Check for I/0 error 

60 BLT ERR4A § Branch on I/0 error 
@ 61 RSUM$C QIOAST ¥ Resume task 

62 RCS ERRS ¢ Branch on dir error 

63 TST CSFO+ + For AST srecific word 
O| « $ off stack 

65 ASTX#$S ¢ Leave AST state and 

66 s return to main code 

67 y AST error handling code 


68 ERR43 QIRERR <ERROR ON QIO BY AST ROUTINE> 

11) 69 ERR4A3 IOERR #TOSBy<ERROR ON QIO BY AST ROUTINE> 
70 ERRS $ QIRERR <ERROR ON RESUME BY AST ROUTINE> 
71 +END START 


Rum Session 


“INSTALL QILOAST 
=RUN QTOAST 


*QTOAST’ IS STARTING 


AST IS EXECUTING ANTI WILL NOW RESUME QIOAST 
“QTOAST’ HAS BEEN RESUMET 


Example 3-3 Asynchronous I/O Using an AST for Synchronization 
(Sheet 2 of 2) 
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TERMINAL I/O 


Device Specific Functions 


Some device-specific function codes are listed in Table 3-3. 
Table 2-3 in section 2.3 (on the QIO macro) of the RSX-11M/M-PLUS 
I/O Drivers Reference Manual lists all of tthe available special 
functions for the full-duplex terminal driver. As noted, some of 
these functions are SYSGEN options. 


Many of the device-specific functions are selected using 
subfunction bits. These bits may be ORed with standard or 
device-specific function codes to produce special functions. 
Table 2-4 in Chapter 2 of the I/O Driver's Reference Manual lists 
the various combinations which are possible. For example, TF.TMO 
(read with timeout) ORed with a read function (IO.RLB, IO.RPR, 
IO.RNE, etc.) terminates the read if the specified time period 
goes by between keystrokes. Notice that some device-specific 
functions, such as Read No Echo (I0.RNE), have equivalents using 
subfunction bits (IO.RLB!TF.RNE). Read After Prompt (IO.RPR) on 
the other hand, has no equivalent using subfunction bits. 


NOTE 
When you OR subfunction bits with read or 
write functions, use Read Logical Block or 
Write Logical Block, not the Read Virtual 
Block Or Write Virtual Block. If the 
Executive converts a virtual block operation 
to a logical block operation, any subfunction 
bit settings are lost. 


For additional information on the device-specific function 
codes, see section 2.3.2 on Device-Specific Functions in the 
RSX-l11M/M-PLUS I/O Drivers Reference Manual. Examples of the use 
of Read After Prompt, Read No Echo, and Read With Timeout are 
included here. 


I/O Status Block and Terminating Characters 


As for other I/O functions, the low order byte of the first 
word of the I/O status block contains the I/0O status byte, 
indicating the success or failure of the I/O operation. Also, the 
second word contains the count of characters actually transferred. 
For reads from a terminal, the high order byte of the first word 
of the I/O status block contains the terminating character in 
ASCII (<RET>, CTRL/C, etc.) for successful reads. 
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| Normally, CTRL/Z is treated as an error. The I/O status byte 
is set to IE.EOF (-18.) and the character count contains the count 
of characters read before the CTRL/Z. Example 3-4 shows’ how 
CTRL/Z can be specially handled in a = program. Two special 
function codes, IO.RST and IO.RTT, allow reads to be successfully 
terminated by nonstandard terminating characters. The first 
allows any non-alphanumeric character to terminate input; the 
second allows the user to specify which character or characters 
should terminate the read. 
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Some Special Terminal Function Codes 


monet 
ae 
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Read After Prompt 


The Read After Prompt function allows the combination of a 
write of prompting text followed by a read ina single QIO 
request. System overhead is lower because only one QIO directive 
is processed. In addition, there is no window during which a 
response to the prompt may be ignored. Such a window may occur if 
Separate QIOs are used to write and read, and if there is a delay 
between the write of the prompt and the read. The I/O parameter 
list contains six parameters, three for the read, and three for 
the write. The following notes are keyed to Example 3-4. 


4) Placing the buffer with "You typed:" just ahead of the 
buffer for the input text allows the use of a single QIO 
to write out the complete line of output text. FINMES is 
the starting addres of the output text and length is FLEN 
+ n, where n is the number of characters typed in. 


©@ Wwe assign the symbol IOLEN to the second word of the IOSB. 
This allows you to reference that word with IOLEN, instead 
of using IOSTAT + 2. 


@ IO for Read After Prompt. The function code is I0O.RPR. 
The first three parameters in the I/O Parameter List are 
for the read, the last three are for the write. The write 
is performed first, followed by the read. The 44(8) for 
the vertical format control causes the prompt text’ to 
appear on the next line, followed immediately on the same 
line by the prompt for the read. 


4 We are going to display the message typed, preceded by the 
text "you typed in." By placing the input buffer BUFF 
immediately after the preceding text, we now have our 
output text as one string beginning at FINMES. The total 
length of the message to be displayed is the length of the 
preceding text plus the number of characters typed in. 


5 | Use a normal QIO with Write Virtual Block to display the 
output. 


6 If the operator types a  CTRL/Z, an error status is 


returned. In this case, simply exit normally. Therefore, 
you must check for this condition and handle it specially. 
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i 


a 


’ 
FROM 3 
FLEN 
FINMES ¢ 
FLEN 
BUFF? 


LTOSTAT ¢ 


TOLENS 


; 
START! 


This task rromets the 


echos the string to the terminal. 
Process 


‘USING THE QIO DIRECTIVE 


FROMF T 
/O1/ 
Le 3 


+ TITLE 
+ INENT 


+ENABL Enable lower case 


File FPROMFPT.MAC 


input string and 
It rereats this 


user for an 


until the user tyres a CTRL/Z. 


Assemble and task-build instructions? 


MACRO/LIST LBiC1ls1IPROGMACS/LIBRARY » devi CuicIFROMPT 
LINK/MAP PROMPT» LB C1» LIFROGSUBS/LIBRARY 


*MCALL 


EXITS$S »QLOWtS § System macros 
«MCCALL 3 $ 


NIRERR»s IOERR urpelied macros 
~-ASCII /FPlease tyre anything? 7 ¢Fromet 
= «7FPROM § Length of rromret 


y 
*ASCII You tyred? 7 § Echo rrefix 
= 2~FINMES §¥ Length of above 
+ BLAKE 80. ¢ Buffer 
«EVEN 3’ Move to word boundary 
+ BILKW 1. § I/O status block for 
> QTOs. 
+BLARW 1 § 2nd word of I/0 status 
§ block 
QLIOWSS #IO.RFP Re #5 #12» FLOSTATs » <#BUFF x $806 9 ye EPROM SPLEEN: #44> 
y issue QIO for Read 
’ After Fromet 
RCS — TERR * Branch om dir error 
TSTE IOSTAT ¢ Check I/0 status 
BLT IERR § Branch om I/0 error 
Alt #FLENy IOLEN § Add length of rrefix 
y to that of entered text 
QLOWSS #IO.WVRs t5et1 yy FLOSTAT» » S#F INMES s IOLENs #40> 
, > Write the new messede 
RCS CERR y Kranch om dir error 
TSTE IOSTAT * Check for I/0 error 
BLT OERR § Branch om I/0 error 
BR START * Start over asain 


$s Errors come here 


DERR 3 


CERR 3 
IERR¢ 


JERR 3 


DOERR $ 


Example 3-4 


QIRERR <Error in QIO to READ AFTER FROMFPT> 
’ Use macro to tell of 

QIRERR <Error in QIO to WRITE> ¢ dir error 
CMF EB ¥#IE.EOQF»sTOSTAT y Check for “Z 
BNE JERR > Branch if motes 

$ was I/O error 
EXITS § Normal exit 
IQERR #IOSTATy<Error in READ AFTER FROMPT> 

+ Use macro to 

+ tell of 
IOERR #IOSTATs<Error in WRITE> ¢ I/0 error 
+ ENT! START 


Prompting for Input (Sheet 1 of 2) 
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Rum Session 


*RUN FROMFT 

Flease tyre anything? sJkshJHGJHGHFY134435 
You tyred? sJkshJHGJHGHF Y134435 

Flease tyre anything? hello there 

You tured? hello there 

Flease ture anything? “Z 


Example 3-4 Prompting for Input (Sheet 2 of 2) 
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Read No Echo 


Read No Echo is used to override the default of echoing’ each 
character as it is typed. This is used for passwords and other 
private information. Example 3-5 uses this’ function. The 
following notes are keyed to the example. 


@ The .NLIST BEX assembler directive instructs the assembler 
not to list binary code which takes up more than one line. 
This saves room in the listing for all the ASCII text. 
Return to listing binary extensions for the code by using 
a .~LIST BEX assembler directive. 


6 As in the previous example, we display the text typed in, 
preceded by our own message. Since the Read No Echo 
doesn't echo any characters back and thus doesn't move the 
cursor on the screen at all, precede the text with a 
carriage return (15(8)) to get the cursor back to the 
Start of the line. If this is not done, the NO LONGER A 
SECRET WORD message will begin away from the left hand 
margin, below the : in "SECRET WORD". 


3) Write prompting text, then leave cursor at that position 
for input (since 44(8) is used for vertical format 
control). 


4 | Read No Echo QIO. Standard read parameters except for the 
function code. 


@ As in the previous example, add the length of the 
preceding text to the text typed in to determine the total 
length of the output message. Here, however, you do_ the 
calculation in a register instead of in the IOSB. Since 
the Read No Echo doesn't echo any characters back, it 
doesn't move the cursor on the screen. Therefore, precede 
the text with a carriage return (15(8)) to move the cursor 
back to the start of the line. Without it, the "NO LONGER 
A SECRET WORD" message will begin away from the margin, 
below and after "SECRET WORD: ". 


You can combine the write of the prompt and the read into one 
QIO directive call using a Read After Prompt with the Read No Echo 
subfunction bit (IO.RPRITF.RNE). If you want, imbed the carriage 
control characters in the message. 


126 


tha 


OE N HOD 


1 


+ 
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BLEN 
BUF $ 


TOSE? 
LENT? 


START? 


TERRA 
TERR23 
TERRS $3 
QERR A 3 
TERR 3 
DERRS 3 


This task 


USING THE QIO DIRECTIVE 


«TITLE 
+ IDENT 
+ENARL 


rromrts for inreuty 
disrlays the inreut text and exits. 


NOECHO 
/O1/ 
LC 3 


FILE NOECHO.MAC 


Enable lower case 


reads it without echoy 


Assemble and task-huild instructions?’ 


MACRO/LIST LE? C1ir1IPROGMACS/LIBRARY »deviCuicINOECHO 
LINK/MAF NOECHOsFROGSUBS/LIBRARY 


s Errors come 


+MCALL 
*MCALL OIRERRs IOERR ; 
«NLIST BEX # 

Le 
*ASCII /SECRET WORD? 7 3 
= eo“ MES $ 
*ASCITI 

¥ 
= «~ BUFF 3 
eBLKE 80. $ 
»EVEN ; 
»WORT 0 3 
»«WORD 0 3 

gy 
+LIST BEX 3 
QTOWS$C TO.WVB»Svl+,TOSBs 

¥ 
BCS NERR1 ; 
TSTE IOSB 7 
BLT IERR1 ? 
QTOW#C IO.-RNE+SsiveTOSKs 
RCS NERR2 3 
TST IOSG $ 
BLT IERR2 ; 
MOV LENT »RO 3 
Ann #BLENyRO 3 
QTOWSS 

? 
BCS TERRS 3 
TSTR IOSE $ 
BLT ITERRS ; 
EXIT#S ; 

here 

LOERR #TOSKy<Error on ist WRITE> 
IOERR #IOSBy<Error on READS 
IOERR #IOSBy<Error on 2nd WRITE 
QIRERR <Error im QIO on 
QNIRERR <Error in QIO on 
NIKRERR <Error in QI0 on 
+ENT START 


Example 3-5 


EXIT#SsQIOWSCsQIOWSS § Sustem macros 


Surrelied macros 
Ton’t list binary 
extensions 
Fromet messese 
Length of rromet 


“<15>/N0 LONGER A SECRET WORD? / 


Freceding remark. 

Length of Remark 

Ineut buffer 

Word align for IOSE 
IOSK is broken into 
two rarts for 
convenience. 

List binary extensions 


yiMESrsLENv44> ¥ Write 


reromret 

Branch on dir error 
Check for I/O error 
Branch on I/0 error 


yi BUF »80.> § Read Noecho 


Kranch on dir error 
Check for I/0 error 
Kranch om I/O error 
Get length of inreut 
Add length of remark 


#IO.WVRs #59419 2 #TOSRs o SEBUFF oe RO ye $40> 
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Write out text 
Rranch om dir error 
Check for I/0 error 
Rranch om I/O error 
Mit 


Nisrlay I/0 
messasde and 
ait 


<s> > G> 


lst WRITE: § Diselay dir 
REATZ y Mmessaste and 
2nd WRITES ¢ Hit 


Read No Echo (Sheet 1 of 2) 
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Run Session 
RUN NOECHO 


SECRET WORDS 
NO LONGER A SECRET WORD: Ann 


Example 3-5 Read No Echo (Sheet 2 of 2) 


Read with Timeout 


Example 3-6 is a repeat of Example 3-1, only with a timeout 
on the read. The following notes are keyed to the example. 


To invoke the timeout mechanism, TF.TMO is ORed with’ the 
read function (IO.RLB). You must use Read Logical Block 
here, because any subfunction bits are stripped off when a 
Read Virtual Block is translated to a Read Logical Block 
function. In addition, the third parameter in the I/0 
parameter list specifies the length of the timeout in 19 
second intervals. This timeout occurs if that amount of 
time passes between successive keystrokes. If a timeout 
occurs, input is terminated, but no error is’ reported. 
Instead, the success code +2 is returned rather than the 
Standard +l. 


On the Run Session —- In the first run, the QIO timed out 
after KJHKJ}}j}. In the second run, the QIO was terminated 
with a carriage return before it timed out. 


To handle the timeout specially, just check the I/O status 


byte 


for a value of +2 (IS.TMO). Another alternative for placing 


a time limit is to use a Mark Time directive (MRKT$). The timeout 
with a Mark Time is for the entire input, rather than for the next 
keystroke. 
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+TITLE QIOTIM 
+IQENT /0O17 
+ENABL LEC 5 Enable lower case 


+ 


FILE QIOTIM.MAC 


This task reads @ line of text from the terminal» 
converts @1ll urrer case characters to lower casey ane 
Frints the converted messase back at the terminal. It 
uses syumchronous QTOss with @ timeout on the read. 


“> “Gh “> > “Sr “E> “EP “E> “E> 


i 


*MCALL QTOWSCyQTOWSS*EXITSS § System macros 


I/O Status Block 
Text buffer 


IOSE? + BLAW 2 
BUFF $ » BLAKE 80. 


Scr “Sr 


Error Count 

Error indicator ~- 0 
means directive errory 
(SW in R3)* nest means 
I/O error (1/0 status 
im R3) 

QIOWSC ITO.RLB!ITF.TMOsSelse+TOSKs »<BUFF s80.91> 

Issue read 


START? CLR RS 
CLR R4 


Sr Sh SP Mh Sh SD 


RCS ERR1 Branch on dir error 

TSTE IOSE& Check for I[/0 error 

BLT ERRIA Rranch om I/O error 

MOV ITOSK&+2sR0 Get count of characters 
tyred in 

CLR Ri Offset into buffer to 


character 
Check for urrer case 
ASCII character 


LOOF 3 CMFRB BUFF CRI)» #°A 


SP We Sh Wr > WC> “EP “ES SH Wh “MD 


BLT NEXT Rranch if below ranse 
CMF R BUFF CRI) 9 #°Z 
BGT NEXT § Branch if above ranse 


5 It is urrer cases so move to resister R2 and convert 
MOVE RUFF CRI? sR Move to resister 


“Sy 


ALL #32.9R2 + Convert to lower case 
MOVE R2»s BUFF CRI) + Rerlace in messase 
NEXT? INC Ri i Increment offset into 
+ huffer to mext char 
SOR RO» LOOF + Ttecrement count of 
¥ 


characters left 
QTOWSS #IO WVBR #59 ¢1% » €TOSBy » S#BUFF y TOSR+2 2 #40> 
BCS ERR2 ’ Branch on dir error 


Example 3-6 Read With Timeout (Sheet 1 of 2) 
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. 48 TSTE IOSE 

49 BLT ERR2A 
50 EXITS 

Si $ 

go y Error code 

53 5 

34 ERR2At INC RS 

35 ERRIA? INC RS 

36 MOVE IOSKs RS 
57 REC R4 

58 

39 IOT 

60 ERR23 INC RS 

61 ERR13 INC RS 

62 MOV $NiSW » RS 
63 

64 TOT 

65 *END START 


Rum Session 


*RUN QIOTIM 
KJHK J 

Jk SS 
=RUN QIOTIM 
JIJathk JfiurctRetT> 
Ada fnk Jf iur 


Example 3-6 
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“O> sae 


S> > “GP “GP Wr a> “SP Ch Ge GP ‘er 


Read With Timeout 


Check. for I/O error 
Branch on I/0 error 


RS=2,% 2nd QIO 
RS=1y ist QIo0 

I/0 error. [70 status to R4,. 
Nedative value in R4 

means I/O error 

Trar and disrlay resisters 
RS=2» 2nd QIO 
RS=1ly ist QIO 
Directive error. TSW 

to R3: leave R4=0,. 

Trar and disrlay resisters 
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Terminal-Independent Cursor Control 


Terminal-independent cursor control is a SYSGEN_ option, 
provided only if selected. If it is selected, certain I/O 
requests are automatically converted by the terminal driver for 
the specific device for which the I/O request is made. This is 
typically done with escape sequences used for positioning the 
cursor. This allows a task to move the cursor to any position on 
the screen and then write a message. 


This can also of course be done by imbedding the terminal 
specific escape sequences into the write buffer. However, the 
advantage of using terminal-independent cursor control, is’ that 
the same program will work at different terminals (VT-52's and 
VT-100's, for example), without any need for modification. 


All you need to do is place the proper value in the vertical 
forms control word of the I/O parameter list. If the high order 
byte is non-zero, then the word is interpreted as a cursor 
position. The high order byte is the line number, and the low 
order byte is the column number. Home position, the upper left 
corner of the screen, is defined as line 1, column l. 


To start the display at line 19., column 25., place a 1g. in 
the high order byte and a 25. in the low order byte. An easy way 
to do this is to let the assembler convert 1@0.*256.!25. for you. 
In general, X*256.!Y corresponds to position X,Y on the screen. 
In addition, if bit 15 (the most significant bit in the line 
number byte) is set, the screen is cleared before the cursor is 
moved. 


Example 3-7 demonstrates the use of terminal-independent 
cursor control. The following notes are keyed to the example. 


4) Parameters defined with symbols so that they can easily be 
changed. 


6 Use the $ form of the mark time directive to allow reuse 
of a single DPB. 


6 Issue a mark time directive for one minute to set event 
flag 3, allowing the task to exit after one minute. 
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Modify the DPB and use it over and over again, at line 34, 
to mark time for Z seconds before updating the display. 
The second mark time uses event flag 2, to avoid 
conflicts. This approach saves task space since the DPB 
is used again. 


Issue the Z second mark time directive. We will wait for 
event flag 2 at line 5@. When one second goes by and the 
flag is set, check for one minute and update the display 
again if it hasn't yet gone by. 


Get the time and date parameters in binary. 


Use the System Library Route $DAT and STIM to format’ the 
date and time for display. See Chapter 6 of the 


IAS/RSX-11 System Library Routine Reference Manual for 
documentation on these routines. 


Calculate the length of the output message by subtracting 
the starting position in the buffer from the position 
after the last character in the buffer. 


Issue the write. xX*256!Y places the cursor before the 
write at line xX, column Y. The TF.RCU subfunction bit 
instructs the terminal driver to save the cursor position 
before moving it, and then to restore it after writing the 
message. This allows you to continue typing in commands 
while the task runs. 


Wait for z seconds to go by. The mark time directive will 
cause event flag 2 to be set. 


Check event flag 3. If it is set, the one minute is up 
and you should exit. Use Clear Event Flag instead of Read 
All Event Flags so that the DSW will indicate whether’ the 
flag was clear or set before you cleared it. With Read 
All Event Flags, the settings of flags 1-16 are returned 
in a word ina buffer. You would then need to test the 
specific bit to check the flag setting, which is more 
work. 


On the Run Session - The display actually will appear at 


line X, column Y on the screen, and is updated every z 
seconds. 
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1 +TITLE DATTIM 

2 +LQENT /01/7 

2 *ENABL Le * Enable lower case 

4 ++ 

3 5 FILE DATTIM.MAC 

& Fy 

? $ This task elaces the date and the time at line X» column Y and 
8 > then urdates the disrelay every Z seconds for 1 mirute. 

9 j 
10 i Assemble and Link instructions? 

Li ; 
12 ; MACRO/LIST LEi Cis lIFROGMACS/LIBRARY sdevi lCufdITATTIM 
13 } LINK/MAF DATTIMe LB? Lis LIFROGSUBS/LIBRARY 
14 5 
1S +MCALL QTIOWSS »sMRKT#eWTSESC »GTIMSC §¢ External system macros 
14 *MCALL EXIT#S sCLEF S&C s DIRE 3 
17 *+MCALL JIRERR» TOERR i External surrlied macros 


18 3; Tate 


19 X=B i Line mumber 

1) 20 Yur 32s § Colunm mumber 
21 L215 + How often to urdate Cin seconds) 
“3 2 


Buffer for return of sustem time 
Ruffer for creating outeut message 
I/0 status block 

FEB for mark time directive 


ae TIMBUFS .BLAW 8. 

24 TIMMSG? «BLAEB 20-e 
20 LOSEk?3 + BLARW re 

26 MRKTM$ MRKTS Syiv3 
a? § Code 


“> “Mr “Me “OD 


3) 2B STARTS YIRS MRAKTM § Set ur tao exit after 1 minute. 
29 RCS ERR I § Branch om directive error 
30 i Setour for the other mark time directive 
31 MOY 2 oMRRTM4+M.KTEF ¢ Change event flas + 

o| MOV #Z°MRKTM+M.KTMG ¢ Change time magnitude 
33 MOV #2>MRKTMtM.KTUN ¢ Chansde time units 

5 34 AGAIN: DIRS EMRRTM § Schedule nmaxt update 
35 RCS ERR? 5 Branch on directive error 

6 36 GTIM#C TIMBUF § Get sustem time and date 
37 RCS ERRS § Branch on directive error 
38 MOV #TIMMSGsRO + Set ur for call to #0AT 
39 MOV #TIMBUF ss RI 3 
40 CALL $0AT s Convert date for disrlay 

7 41 MOVE #! » CROD+ * Insert srace into outrut messade 
42 MOV #39R2 > Set ur for call to $TIMy ask 
43 3 for HHiMM?SS format 
44 CALL. $TIM > Convert time for diserlay 

8 4S SUE tT IMMSG » RO “§ Comrute character count 

O46 QIOWSS #LOWWLBITFE RCUs#Sy #12 os # LOS: y CA TIMMSG yo ROv EXK2SS,. LYS 

47 BCS ERR41 + Branch on directive error 
48 TSTE IOSE § Check for I/Q error 
4D RL. T ERR41T > Branch om I/0 error 

® IQ) WISE$C 2 § Wait for mark time to exrire 
wd RCS ERRS § Branch om directive error 


Example 3-7 Terminal-Independent Cursor Control (Sheet 1 of 2) 


133 


S2 3 
@ 5: 
54 
Kal be 
36 
37 
38 
heed § Error 
60 ERR1? 
él ERR23 
62 ERR3?3 


63 ERR403 


64 ERR4T 3 
65 ERRS 

46 ERR&3 

67 


Rum Session 


© 


“RUN DATTIM 


Example 3-7 


CLEF SC 
BCS 
CMF 
REQ 


EXITS 
code 
INIRERR 
DNIRERR 
DNTRERR 
DIRERR 
IOERR 
IIRERR 
DIRERR 
«ENT 


USING THE QIO DIRECTIVE 


3 

ERRSG 
$LISW > #1 
AGAIN 


ERROR 
ERROR 
ERROR 
ERROR 
#IOSBy = 
“ERROR 
“ERROR 
START 


Check for i minute gone by 


Clear event flast to check setting 

Branch om directive error 

Check for flas already clear 

If still clearry minute not ur vets 
urdate disrlay asain 

Exit if 1 minute is ur 


S+CLR 


‘S> “Eh Se Ge “Ge ‘C> 


ON MARK TIME FOR 1 MINUTE> 
ON MARK TIME FOR 1 SECOND 
ON GET TIME> 

ON WRITE 

ERROR ON WRITE? 

ON WAIT FOR? 

ON CLEAR EVENT FLAG> 


12-MAR~-82 11312354 
! DISPLAY WILL START AT LINE Sv: COLUMN 32 


Terminal-Independent Cursor Control (Sheet 2 of 2) 
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Formatting Output Data 
The subroutine S$EDMSG in SYSLIB.OLB provides a generalized 
output formatting capability for easily creating display messages. 
It is useful if some of the data is generated at run time. This 
allows you to combine a number of functions available with 
individual conversion routines (such as $CBDMG) for converting a 
Single binary word to an ASCII octal string for display. It 
includes all of the following functions. 
e Conversion of internal binary stored data to 
- ASCII signed or unsigned octal 
- ASCII signed or unsigned decimal 
- ASCII alphanumeric characters 


e Conversion of time or date data into standard ASCII 
formats (hh:mm or dd-mmm-yy) 


e Formatting of converted characters’ for display, by 
themselves or intermixed with other text. 


For a complete discussion of the use of SEDMSG, see Chapter 5 


of the IAS/RSX-11 System Library Routine Reference Manual. 


To invoke SEDMSG, use the following procedure. 


1. Set up the output buffer, the format string, and _ the 
argument block. 


2. Set up the input parameters. 
R@ - starting address of output buffer 
Rl - starting address of format string 


R2 - starting address of argument block, containing 
the data to be converted 


3. Call SEDMSG. 
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On return, the converted/formatted string is in the output 
buffer. The output parameters are: 


R@ - Address of next available byte in the output buffer 
Rl - Length (in bytes) of the output string 


R2 - Address of the next argument in the argument 
block. 


NOTE 
The output parameters make it possible _ to 
concatenate messages uSing multiple calls to 
SEDMSG. 


The output buffer is a buffer in which SEDMSG generates’7 the 
output message. It is typically set up using the .BLKB or .BLKW 
assembler directive. The format string is set up using a 
combination of ASCII text and editing "directives." It must be in 
ASCIZ format, meaning that it is terminated by a Q@(8). The 
editing "directives" are in one of three formats, as follows. 


%d - Means perform directive d once 
nd —- Means perform directive d n-times 


%Vd —- Means perform directive d V-times, where V is an 
argument in the argument block. 


For example, if 0 means convert binary word to ASCII signed 
octal, %O means convert the next word in the argument block to 
ASCII signed octal in the output buffer. %30 means convert’ the 
next three words to ASCII signed octal in the output buffer, 
separated by tabs. %VO means get the binary word in the argument 
block and convert that many words in the argument block to signed 
octal in the output buffer. 


Table 3-4 shows many of the editing directives available with 
SEDMSG. An example follows the table. 7 
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O DIRECTIVE 


Ives for SEDMSG 


lrect 


Sample Editing p 


Table 3-4 


errs 
Segue 
ad 


SEES 


ae 


oe 


es: 
oe 


2 
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Example: 


FORMAT: .ASCIZ /%10$NAME IS $5A AND # IS %D/ 


- EVEN 

OUTBUF: .BLKW 80. 

DATA: -WORD ADRNAM 
-WORD 234 

ADRNAM: .ASCII /BILLY/ 
- EVEN 
MOV #OUTBUF, R@ 
MOV #FORMAT, R1 
MOV #DATA, R2 
CALL SEDMSG 


The resulting string in OUTBUF would display as: 


NAME IS BILLY AND # IS 156 


Explanation: 


$18S in the format string - Produces 19 spaces in the output 
buffer. 


NAME IS —- Placed in the buffer as is. 

$5A -—- Get five bytes and convert to ASCII. Because’ the 
argument block is set up on a word-by-word basis, place the 
address of the ASCII characters (ADRNAM), instead of the 
ASCII characters themselves, in the argument block. 

AND # IS - Moved to the output buffer as is. 

%D -— Get the next binary word in the argument block and 
convert it to Signed decimal in the output block. 234(8) is 
converted to +156(190). 


No decimal point is appended to decimal numbers unless- you 
specify %D. (including the ".") in the format string. 


138 


USING THE QIO DIRECTIVE 


Three examples follow which demonstrate the use of the $EDMSG 
routine. 


Examples of Formatting Numeric Data 


Example 3-8 shows the use of SEDMSG for formatting numeric 


data. 


The following notes are keyed to the example. 


This is the argument block, which must be ae set of 
contiguous words. 


This example uses the $ form of the QIO directive. The 
length of the buffer to be written out will be filled in 
at run time. 


The output buffer starts at BUF and is 8@. bytes’ long. 
This buffer should be long enough for at least the longest 
message that you might generate. 


The format string. Note that three words will be 
converted to signed decimal ASCII using S$EDMSG. The 
-ASCIZ assembler directive assures that the format string 
ends with an octal @. 


Set up input parameters for call to SEDMSG. The addends 
and the sum are already in the argument block. 


Invoke SEDMSG. The output string is returned at BUF. Rl 
contains the count of characters in the output string. 


Move the count of characters to be written into the DPB of 
the QIOS directive. 


Write the results out at the terminal. 


Normally, the addends might be placed in the format string if 


they 


are known at assembly time. Only data generated at run time 


would be converted using SEDMSG. 


139 


USING THE QIO DIRECTIVE 


Example 3-8 
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Formatting Numeric Data 


1 +TITLE NUMER 
2 *+IQVENT /017 
3 *+ENABL. LO ys Enable lower case 
4 5+ 
ba ¢§ FILE NUMER.MAC 
6 > 
? ¢ This task does a simrple addition and outruts the 
8 s results. It demonstrates the use of $E0MSG for 
9 * formatting messases with numeric data 
10 3 
ii *+MCALL. QIOWSvEXIT#Ss DIRS § Sustem macros 
12 *+NLIST BEX y To not list binary 
13 y extensions 
14 § Data 
LS A3 +WORT 10 § ist addend and start 
16 >: of arsument block 
17 Ri »WORTD 22 y 2nd addend 
18 C3 +BLKW 1 sy Location for sum 
19 7 
29 OUT? QIOWs TO.WVBy Sele rsTOSBys<BUF ss40> $¢QI0 for 
24 § OUtFUL messase 
22 LOS? + BLAKW 2 I/O status hlock 
2c ; 
24 > Set ur for $E0MSG 
2 3 
26 RUF + BLAKE B80, > Outeut buffer 
QO» FMES? *ASCIZ /40. WAS ALTED TO 40.» GIVING “40.7 
28 * Format strings 
29 
30 +LIST BEX * List binary extensions 
ot »EVEN § Move to word houndary 
32 START: MOV Arlt § Move ist addend to sum 
33 + word 
34 AL Bel ¥ Add 2nd addend to form 
35 y Stim 
36 > Set ur for call to $E0MSG 
37 MOV ¥#BUF » RO § Addr of outrut huffer 
E MOV #FMES*R1 s Addr of format string 
39 MOV #AsR2 * Addr of arsument block 
40 CALL $E MSG ’ Make cally character 
4l y count returned in RI 
42 MOV RisOUTHQ.IOPL4+2 3 Place # of characters 
4S § to write into TOPL 
44 y in QIO DPE 
45 DIRS #OUT ’ Write outrut messasce 
AG RCS ERRAT § Branch on dir error 
47 TSTEB IOSE y Check for I/0 error 
48 BLT ERRiI ¢ Branch on I/0 error 
49 EXITS 
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uo s Error handlines 

oi ERRi0tg MOV $ISWy RO + Move [1ISW for disrlay 
oe CLR Ri § Indicate dir errory hy 
53 § Oin RI 

54 IOT 

35 ERRIIT? MOVE IOQSEB»RO § Move I/0 status for 
36 s disrelay 

a7 MOV #~-19R1 § Indicate I/O error by 
58 > -i in RO 

a9 IOT 

50 +END START 


Kur Session 


“RUN NUMER 
8. WAS ANDER TO 18.» GIVING 264. 


Example 3-8 Formatting Numeric Data (Sheet 2 of 2) 


Example 3-9 shows how to use SEDMSG to generate error 
messages for display. This is a modification of Example 3-1 
(SYNCHQ.MAC). These error routines will typically replace trap 
routines which might be used early in the debugging stage of an 
application. The supplied macros DIRERR and IOERR have’ performed 
Similar functions for you. The following notes are keyed to the 
example. 


@ This is the assembly time setup for $EDMSG. ARG is’ the 
Start of the one word argument block. EBUFF is the start 
of the buffer in which error messages are to be built. 
FMT1, FMTI1A, FMT2, FMT2A are the format strings for the 
various error messages. FMTl and FMT2 are for directive 
errors; FMT1A and FMT2A are for I/O errors. The 
quotation marks are used as delimiters in two of the 
format strings because the strings contain slashes (/). 


@ The main code is the same as_ before. Only the error 
handling is different. 


3 | For each error, move the address of the appropriate format 
String into Rl (for the call to S$EDMSG). Then move the 
DSW into the argument block for directive errors, and the 
I/O status into the argument block for I/O errors. 
Because the I/O status is a byte, move it to Rl first and 
then to the argument block, in order to extend the sign 
bit to the high order byte (see lines 9864 and 9665). 
Then branch to the final setup for SEDMSG at EDAWT. 
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Move the address of the output buffer to R@ and of the 
argument block to R2. Then call SEDMSG. 


Finally, write the formatted message out at the terminal 
and exit. 


On the Run Session —- The first run shows a_e successful 
read. The second run shows an error caused by a “Z. 
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1 +TITLE SYNQER 

2 +IDENT 7/017 

3 *ENABL LC y Enable lower case 

4 s+ 

5 § FILE SYNQER.MAC 

& ; 

7 >’ This task reads a line of text from the terminal» 

8 ’ converts all urrer case characters to lower casey and 
9 3 Frints the converted messadge back at the terminal. It 
10 3; uses sunmchronous QIO. It also uses $EDMSG to generate 
11 y error messages 
12 j- 
13 *MCALL QIOWSCsQIOWSSeEXITSS + Sustem macros 

14 


I/0 Status Block 
Text nuffer 


1S IOSE: + BLAU 2 
16 BUFF 3 +» BLKB 80. 


ser» “GP 


17 

i8 > Set ur for error messages using $EDNSG 

19 

20 ARG? + BLKW 1 Argument block 


a> “Gr 


21 ERUFF 3 + BLKB 80. Outeut buffer 

1) 22 FMT1? *ASCIZ /PIRECTIVE ERROR ON READ DSW = ZL 
23 FMTiA3 .ASCIZ ’I/0 ERROR ON READ: I/70 STATUS = ZI’ 

24 FMT23 *ASCIZ /DPIRECTIVE ERROR ON WRITEs DSW = “2D/ 

20 FMT2A?2 .ASCIZ ’1I/0 ERROR ON WRITE? I/O STATUS = ZI’ 


26 +EVEN 

27 

28 START? QIOWSC ITO.RVBsSsivssTOSBys<BUFF s80.740> ¢ Issue 

29 y Tread 

30 BCS ERR * Branch om dir error 

31 TSTE IOSE § Check for I/0 error 

32 BLT ERRILA + Branch on I/O error 

ao MOV TOSE+2 9RO § Get character count 

34 CLR Ri + Offset into buffer to 

33 > cheracter 

36 LOOF? CMF E BUFF CRI) s#/A § Check for urrer case 

37 y+ ASCII character 

38 BLT NEXT y Rranch if below range 

39 CMF EB BUFF CRI) 9 #°Z 

40 RGT NEXT Branch if ahove ranse 
2) 41 + Here if urrer casey move to resister R2 and convert 

42 MOVE BUFF CRIs R2 § Move to resister 

43 ALL #32.9R2 * Convert to lower case 

44 MOVE R2*s BUFF CRI) s Rerlace in messase 

43. NEXT? INC Ri y Increment offset into 

4G $ huffer to next char 

47 SOR RO» LOOF § Tecrement count of 

48 y chars left to check 


49 QIOWSS #IO.WVE ry t5 5 #17 e#LOSBs » RUFF ey TOSB+2 » €40> 


50 y Write text 

Si RCS ERR2 3 Branch on dir error 
a2 TSTE IOSH ’ Check for I/0 error 
od RL.T ERR2A * Branch om I/0 error 
54 EXIT#$sS ¢ Exit 


Example 3-9 Formatting Directive and I/O Error Messages 
(Sheet 1 of 2) 
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babe 3 
36 > Error code 
a7 3 
38 ERRIA? MOV #FMTIArR1 § Format string for 
59 § ist I/O error messase 
40 BR ERRGOA ¥ Branch to common I/0 
61. § error code 
62 ERR2A MOV #FMT2ZA9R1 § Format string for 2nd 
63 § I/O error message 
64 ERRGOA? MOVE IOSE»RO § Extend sign om I/0 
65 MOV ROs ARG § status byte by moving 
66 y it throush RO to the 
3 | 67 y ardument block. 
68 BER EDAWT + Branch to common edit 
49 y and write code 
70 ERRIY MOV $FMT1iski > Format string for ist 
71 § directive error 
72 BR ERRGO § Branch to common 
73 * directive error code 
74 ERR? ? MOV #FMT29R1 § Format string for 2nd 
73 §s directive error 
76 ERRGO? MOQV $$lTiSWys ARG | § Move [SW to ars block 
77 + Finish setting ur for $E0MSG 
78 EXAWT? MOV #E BUFF es RO § Outeut buffer address 
o| % MOV — #ARG»R2 > Arsument block address 
80 CALL $EDMSG § Edit outeut string 
6 81 QLIOWSS #10.WVRs #5 et] ery es kE BUFF eR1s#40> § Write 
82 y Out message 
83 EXITS y Exit 
84 *END START 
Rum Session 


SRUN SYNQER 

SKJOUSHK JINHE Jk Uhh Uhh yutduveJherwerJwli2 
ok Jdshk Jknk Jk hk Unk vutduge jherwerJjwll2 
“RUN SYNQER 

dhfiooi IKRLHIGHIGJHG"Z 

r/0 ERROR ON READy I/0 STATUS = -10 


Example 3-9 Formatting Directive and I/O Error Messages 
(Sheet 2 of 2) 
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Formatting ASCII Data 


Example 3-9 demonstrates the use of SEDMSG for formatting 
ASCII data. The only real difference between formatting ASCII 
data aS compared to numeric data is that the argument’ block 
contains a pointer to the ASCII characters, rather than to the 
ASCII data itself. The following notes are keyed to the example. 


@e The argument block contains four words. Only the address 
of the number to be typed is known at assembly time. The 
other values will be filled in at run time. In the format 
string, we are using %VA twice. The V tells SEDMSG to use 
the next word in the argument block as the number of times 
to perform the directive A. The directive A means move an 
ASCII character to the output buffer. This allows you’ to 
generate messages of different lengths at run time using 
the same format string. 


©@® an alternative to using TSTB is to use a CMPB instruction. 
IS.SUC is a global symbol equal to +l. 


3) The number typed is in ASCII. We need to convert to 
binary before dividing by two. 


4 | Come here if the number is even. Place the address of the 
message and its length into the argument block. Then 
branch to the common code to generate the message. 


This is the same as in note 4, but for an odd number. 


@ Move the number of digits in the number entered by the 
operator to the argument block; so you display that many 
digits. 


7) Now set up for SEDMSG, format the output message, write 
it, and exit. 


Now do the tests/exercises for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions PEON A GeGs either in that book or 
on-line files. 


If you think that you have mastered the material, ask your 
course administrator to record your progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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l +TITLE FORMAT 

2 +EDQENT /01/7 

3 *+ENABL. LE > Enable lower case 

4 i 

3 * FILE FORMAT.MAC 

4 3 

? i This task asks the user for an inteser. It then 

8 + decides whether the value is even or odds and erints 

9 > am @rrrorriate messase. It demonstrates the use of 

10 + €ENMSG for ASCII data 

Li 5 

12 § Assemble and task-build instructions? 

13 5 

14 3 MACRO/LIST LBRICLsTIFROGMACS/LIBRARY »ydevilufddIrFORMAT 
15 3 LINK/MAF FORMAT sLEt Cl» LIFROGSUBS/LIBRARY 

16 '~ 

17 +MCALL EXIT#SeQITOWStC ,QTOWSS ¢ System macros 

18 *MCALL TIRERRs TOERR § Surprlied macros 

19 
20 MES$ *ASCIT /INFUT A TECIMAL INTEGER BETWEEN 1 ANT 9999/7 
21 > Fromet text 
22 LEN a: eo MES § Lensth of Fromet text 
ae «EVEN 
24 NUM? «BLAKE 4 > Buffer for ASCII #€ aneut 
25 +EVEN 


26 TOSB? WORT 0 ¢ T/0 Status Block 

27 NUMGB? WORT 0 § 2nd word of I/0 Status 
28 § Klock ~- for return of 
29 > # of characters read 


30 § Setur for $ELMSG 
St ARGBLK? 


3a L.NUM 3 »WORTD 0 § Count of cheracters 
33 s in mumber 
34 ANUM 2 +WORT NUM $ Pointer toa mumber im ASCIT 
35 LWORDS »WORTD .¢) § Count of cheracters 
346 § in OT or EVEN 
37 AWORDS WORT 0 > Pointer to O10 or EVEN 
38 § aim ASCIT 
3? RUF 3 + BLAKE 80.  Outeut buffer 
40 OUT? *ASCIZ /SANTHE NUMBER ZVA is Z2VA./ ¢ Format strings 
4 MESE$ *ASCTII EVENS ¢ ASCII text for EVEN 
= LMESE =yeMESE i Lensth of message 
4S MESO? *ASCII /ONT7 ¢ ASCII text for Ong 
44 LMESO =. —~MESO i Length of messase 
43 +E VEN 
44 3 


47 START? QIOWSO TOWVRe Selly TOSRs s<MESsLEN+40> ¢ Write 


48 > Fromet taxt 

49 RCS ERRIT § Branch on dir error 
30 CMFR #IS.SUCsIOSE § Check I/0 Status 

a RNE ERRIT § Branch on I/0 error 
we QLOWSO TO.RVBySelesTOSBs»<NUM*4> ¢ Read ineut 
93 RCS ERR20 § Branch on dir error 
34 TSTE LOSE& + Check om I/0 error 

bi Fa RLY ERR2T * Branch om I/O error 


z 
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Set ur to convert 

. dec ASCII to hinary 
38 CALL $CNTE Comverty result in Ri 
ue * Set ur for divide. Qividend in ROvyR1 combined 


wo MOV ENUM» RO 


ai 
NG 
“Qe ser “ae 


&O CLR RO § Clear high order 16 bits 
61). NIV 2s RO * Ttividey auotient im ROy 
h2 > remainder in Ri 

43 CMF Fed vO + Check remainder 

64 BENE Oon * Branch if mot oO 

65 MOY #LMESE y L WORT + Move lensath of EVEN 

66 > into argument block 

67 MOV HMESE »y AWORD § Move rointer to EVEN 

68 y into arsument block 


Branch to common code 
Move lensdth of O00 

into arstument block 
Move rointer to ON 

into arsument block 
Move # of characters 

im mumber to ars block 
Set our for call to $E0MSG 


69 BR CONT 
70 Ox s MOV TFLMESOvyL WORT 


72 MOV TMESO» AWORD 


74 CONT Ss MOV NUMBE o L.NUM 


‘> "Se MS “A> “A> Mh “Sh “Se 


7S MOV TFRUF » RO 

7? MOV #OUTs RI 

73 MOV TFARGBELKR s Re 
7? CALL $EDUMSG 9 Edit outerut messase 
80 QTOWES #LOWVE sy £5 etd os kTOS Ry » SBRUF e RD #4O> 
Write outrut message 
Branch on dir error 
Check for I/0 error 
Branch om I/0 error 
Exit 


oe 
tad 
nas 
“et 


82 BCS ERR SI 

83 CMFB #IS.SUCsIOSB 
84 BNE ERR SI 

$5 EXIT#S 

84 yi Error nhandlines 

97 ERRIN? DTRERR <ERROR ON WRITE OF FROMFT TEXT> 

$6 ERRLIE? IOERR #IOSBeySERROR ON WRITE OF FROMFT TEXT: 
RY ERR203 DTRERR <ERROR ON REAI 

90 ERR2ZT? IOERR #KIOS By ERROR ON REA 

ot ERR G3 OULRERR <ERROR OUTFUTTING ANSWER? 

Y? ERRSI3 TOERR #HIOSBy<ERROR OQUTFUTTING ANSWER? 

OS e END START 


S> “> GP Sp 


Rum Session 


“RUN FORMAT 
INFUT A DECIMAL INTEGER BETWEEN 1 ANID 9999 
400 


THE NUMBER 600 IS EVEN. 

=RUN FORMAT 

INFUT A DECIMAL INTEGER BETWEEN 1 ANT 9999 
2349 


THE NUMBER 2349 IS ODD, 


oe 
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USING DIRECTIVES FOR INTERTASK COMMUNICATION 


INTRODUCTION 


The RSX-11M program development features allow modular 
development of programs; the multitasking feature allows a 
modular approach to applications. 


A system of multiple tasks may require one or more of the 
following services provided by executive directives under RSX-11M. 


e First task requests that the second task be run. 


e First task is notified of completion of the second’ task 
operation. 


e Tasks pass data to each other. 


This module explains how to use system directives for this 
type of coordination between tasks. 


OBJECTIVES 


1. To use directives which control task execution to 
synchronize cooperating tasks 


2. To use the send/receive directives to pass data between 
tasks. 


3. To write tasks which spawn subtasks using parent/offspring 
directives. 


RESOURCE 


@e RSX-11M/M-PLUS Executive Reference Manual, Chapters 2 and 
4, plus specific directives in Chapter 5 


Lot 
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USING TASK CONTROL DIRECTIVES AND EVENT FLAGS 


It is generally good programming practice to divide a_ single 
complex task into a number of separate tasks, with each task 
performing a distinct logical function. Using a group of tasks to 
perform a complex function frequently makes good sense, especially 
where different parts of the process may run at widely differing 
speeds, each more or less independent of the others. 


Suppose, for example, that you need to simulate customer 
transactions at a_ bank. There are five windows, up to 15 
customers can physically stand in each line at a time, given the 
size of the waiting area. You might design a group of tasks, one 
task per line, to simulate this complex system. This approach has 
the advantage of simulating the related, but essentially parallel, 
processes in a more realistic manner than would a single, serial, 
Simulation. A further advantage of a multitasking approach to 
such a job is that changes in the behavior of the system that are 
caused by changes in a single line (e.g., by assigning different 
types of transactions to different lines) can easily be simulated 
by simply modifying the task that simulates that line. 


An RSX-11M programmer typically uses a mix of the following 
four multitasking methods. 


l. Common or Group Global event flags, together with 
synchronization and task scheduling directives, are used 
to synchronize tasks. 


2. Resident commons are used to share data in memory. 


3. Memory management directives are used to create and/or 
Share data areas dynamically at run time. 


4. File handling routines are used to open disk files’ for 
Shared access. 


The use of shared regions, memory management directives and 
files are discussed in later modules. 
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Directives 


Table 4-1 lists the various task control directives which are 
available for task synchronization. (Most of these were discussed 
in earlier modules.) All of the directives’ are documented 
individually in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual. 


Table 4-2 shows the differences between suspending and 
stopping a task. The major difference is that stopping puts the 
task in a stopped state which effectively lowers the task priority 
to zero, allowing any active task to checkpoint it if it is 
checkpointable. Suspending or waiting, on the other hand, keeps 
the task competing for memory space on the basis of its running 
priority. This means that if the task is checkpointable, only 
tasks of higher priority checkpoint it. Waiting for an event flag 
affects checkpointability the same way as suspending. 


Table 4-3 lists the various event flag directives which are 
available for synchronization. As discussed in Module 2, the 
Clear Event Flag directive (CLEFS$) can be used instead of the Read 
All Event Flags (RDAF$) or the Read Extended Event Flags (RDXFS) 
directives, to check whether a single event flag is set (Since the 
DSW indicates whether the flag was initially clear or set). This 
saves having to check the specific bits in the event flag’ mask 
word. Checking specific bits is necessary with RDAFS$ and RDXFS$ 
because they return several event flag mask words, each containing 
the settings of 16 flags, one flag per bit. 
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Example 4-1 shows the use of the Request Task (RQSTS), 


Suspend (SPNDS), and Resume (RSUMS ) directives for 
synchronization. Notes 1, 2, 3 and 6 refer to TASKA. Notes 4 and 
5 refer to TASKB. 


The supplied macros are used to allow you to concentrate 
on the synchronization techniques. If you want, these 
Macros can be replaced with QIO's and other code. 


TASKA requests TASKB. This means that TASKB must be 
installed under the name TASKB. After this, both tasks 
are active and compete for memory and CPU time. 


TASKA suspends itself. After this it still competes’ for 
memory at its regular priority, but not for CPU time. 


TASKB types out a message and then resumes’ TASKB. More 
typically, TASKB would perform some service for TASKA 
rather than just typing a message. After TASKB- resumes 
TASKA, they both compete for CPU time again. 

TASKB displays another message and then exits. 


TASKA, now resumed, displays a message and exits. 


Depending on the relative priorities of TASKA and TASKB_ and 


on the 


particular task scheduling options on your system (e.g., 


round robin scheduling), steps 5 and 6 may be reversed on the run 


session. 
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+TITLE TASKA 

+IDENT /017 

+ENABL LC y Enable lower case 
FILE TASKA.MAC 


This task reauests TASKE to runs and then susrends 
itself. TASKB resumes this task and exits. 


Assemble and task-huild instructions? 


MACRO/LIST LESCLl»1LIFROGMACS/LIBRARY sdevi CufdITASKA 
LINK/MAF LEAS CL» LITASKA»PROGSUBS/LIBRARY 


Install and run instructions: Both tasks must be 
installed. Just rum TASKA. 


*MCALL. RQSTSCeSFNISGSsEXIT#S § Sustem macros 
*MCALL TYPE sTIRERR ¢ Surrlied macros 


START? TYPE =TASKA BEGINS ANT REQUESTS TASKB> 


> Disrley messade 
RQST$C TASKE + Reauest TASKB 
BCC OK1 * Branch on directive ok 
QIRERR <TASKA UNABLE TO REQUEST TASKE> § Diselay 


a 


' error message and exit 


ORL Ss TYFE “TASKA IS SUSFENTDING ITSELF? + Disrlay 


a 


$ messsde 
SFPNIGS y Susrend self 
BCC OK2 * Branch on directive ok. 
NIRERR <TASKA UNABLE TO SUSPEND ¢ Dliselay 

y error messade and exit 


<2 3 TYPE <TASKA HAS BEEN RESUMED: ¢ Dlisrlay 
5 Messeste 
EXIT$S § Exit 
END START 


Example 4-1 Synchronizing Tasks Using Suspend and Resume 


(Sheet 1] of 2) 
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i «TITLE TASKE 
2 +ITENT /01/7 
3 *ENABL LC § Enable lowercase 
4 3 
Aa y FILE TASKE.MAC 
& 3 
? § This task is activated bu TASKA. It rerforms its 
8 > Oreration and resumes TASKA»s which has susrended 
9 $ itself. 
10. 3 
Li y ASSeMble and Link instructions? 
12 3 
13 3 MACRO/LIST LBtCL»s LIPROGMACS/LIBRARY sdevi CufdITASKR 
14 ; LINK/MAF TASKBRyL Bills LIFROGSUBRS/LIBRARY 
ye 3 
164 § Instell and run instructions? Both tasks must be 
1? * installed. Just rum TASKA. 
18 ; 
1° *MCALL RSUM#CeEXITSS * Sustem macros 
20 »MCALL TYPEsTDIRERR * Surrlied macros 
2 §* Must enable local symbol blocks because we use local 
oe i symbols and QDIRERR has .PSECT statements . 
23 *ENABL, LSE j Enable local symbol 
24 § block. 
2g ; 
26 § Any oreration could be rerformed heres but in this 
27 y Case it’s only @ tyureout. 
28 START? TYPE <TASKE IS ALIVE AND RUNNING? ¢ Disrlay 
4 | 2» > Messase 
30 RSUM$C TASKA i Resume TASKA 
Si BCC 1$ ? Kranch on directive ok 
32 QIRERR <TASKE UNABLE TO RESUME TASKA> ¢ Dliselay 
33 , error messadge and exit 
34 $3 TYPE <TASKB HAS RESUMED TASKA AND IS EXITING? 
5 [is + Lisrlay message 
36 EXITS : Exit 


37 *ENT START 


Rum Session 


INS TASKA 
“INS TASKE 
“RUN TASKA 
TASKA BEGINS ANDI REQUESTS TASKE 
TASKA IS SUSPENDING ITSELF 
TASKE IS ALIVE ANI RUNNING 
TASKA HAS BEEN RESUMED 
TASKE HAS RESUMED TASKA AND ITS EXITING 


Example 4-1 Synchronizing Tasks Using Suspend and Resume 
(Sheet 2 of 2) : 
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Example 4-2 shows the use of event flags for synchronization. 
In module 2, there is a similar example. Here, TASKC requests 
TASKD, rather than requiring an operator to start both tasks. 
Also, the Stop For Single Event Flag is used rather than the Wait 
For Single Event Flag. The difference between them is that’ the 
first causes the task to enter a stopped state and the other 
causes the task to enter a wait for (like a Suspended) state. 
Notes 1, 2, 3 and 6 refer to TASKC. Notes 4 and 5 refer to TASKD. 


@ clear the event flag to initialize it. It's initial state 
is unpredictable, since other tasks may have set or 
cleared it. 

Request TASKD. 

Stop until the event flag is set by TASKD. 

TASKD displays a message and sets the event flag. 


TASKD displays a message and exits. 


TASKC displays a message and exits. 


Depending on the relative priorities of the two tasks, 
significant events in the system, and other scheduling 
considerations, the order of the steps may vary. Specifically, 
steps 3 and 4 above may be reversed, as well as 5 and 6. 


The event flag must be common or group global, not local. In 
either case, the users on the system must coordinate to avoid 
several users uSing the same event flag for different purposes. 
If a group global event flag is used, the flags for that group may 
have to be created uSing either the Create Group Global Event 
Flags directive (CRGFS$) or the DCL SET GROUPFLAGS/CREATE (FLA /CRE 
in MCR) command. 


The Executive scans the Active Task List and schedules’ tasks 
for CPU time only after a significant event. Setting an event 
flag does not cauSe a Significant event. This means that TASKC 
normally won't compete for CPU time until at least the next 
Significant event in the system. If it is important that TASKC 
begin executing sooner than that, TASKD should issue the Declare 
Significant Event directive (DECLS$), which causes the Executive to 
reschedule tasks. For a discussion of significant events, see 
Chapter 2 of the RSX-11M/M-PLUS Executive Reference Manual. 
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1 TITLE TASKC 
2 *INENT 7/017 
3 *ENABL LC ’ Enable lower case 
4 ++ 
5 ¢ FILE TASKC.MAC 
& ; 
7 § This task clears an event Flas» reauests TASK to runs 
8 > and then stors until the flas is set bu TASKE. 
9 # 
10 § Assemble and task-build instructions? 
ii ; 
12 3 MACRO/LIST LBtC1ls LIPROGMACS/LIBRARY +s devs Cufd JTASKC 
13 3 LINK/MAF TASKC sys LB CLs LIFROGSUBS/LIBRARY 
14 3 
15 + Install and run instructions! TASKD must be installed. 
16 § Just rum TASKC. 
17 j- 
18 *MCALL CLEF SC eRAST&CeSTSESCSEXIT#SS ¢ Sustem macros 
19 *MCALL TYPE sTIRERR $ Surelied macros 
20 3 
21 FLAG=33. * Event flags to be used 
22 3 
23 START? TYFE <TASKC BEGINS AND REQUESTS TASKIN 
24 + Tiselay messase 
@ 25 CLEF$C FLAG ? Clear event flag 
26 + hefore storrins 
27 RCC OKL § Branch on directive ok 
28 QIRERR <TASKC UNABLE TO INITIALIZE EVENT FLAG> 
29 > Tiselay error messade 
30 > and exit 
31 OKLS RQST#C TASKO * Reauest TASKD 
32 RCC OK2 § Branch on directive ok 
33 NIRERR <TASKC UNABLE TO REQUEST TASKS + Disrelayw 
34 § error messese and exit 
35 OKR2? TYFE TASKC IS STOPFING FOR EVENT FLAG? 
36 > Tisrlay message 
& 37 STSE$C FLAG § Stor for event flag 
38 § to he set 
39 RCC OKS3 § Branch on directive ok 
40 QIRERR <TASKC’S STOF REQUEST REJECTED? ¢ Disrelay 
4l y error message and exit 
[43 OK3? TYFE <TASKC HAS BEEN UNSTOPFED AND WILL NOW EXIT? 
6 43 § Tiselay message 
44 EXITéS > Exit 
43 »ENT START 


Example 4-2 Synchronizing Tasks Using Event Flags 


(Sheet 1 of 2) 
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+ 


PILE: 4, 


ON & LAD Gh 


which 


~*~ 
“ 
E> Sh Sh “Ah “EP “E> SD “Gr “EP “E> “E> 


LAG=33,. 


Arid ar 
case ji. 


23 START? 
24 
25 


hh 
°o 
{fl <a> “> <a> ar “TE <a> 


Si OR? TYFE 


*TITLE TASKY 
IDENT /017 
*ENABL LC 


ASKIN. MAC 


TASKC is storred,. 


“ 
¥ 


This task is activated bye TASKC. 


Enable lower case 


It sets the flags for 


Assemble and task-build instructions? 


MACRO/LIST LES C1» IPROGMACS/LIBRARY »devi »Cufd I TASKH 
LINK/MAF TASKILBS CLs. IFROGSUBS/LIBRARY 


*MCALL SETFSCrEXIT#S 
*MCALL TYPE STTRERR 


eration 
t’s onmiuw 3 tyureaut. 
TYPE “=TASKO IS ALIVE 


SETFSC FLAG 


BCC OK 
DIRERR 


33 EXITS 


Run Session 


“INS TASKC 
*RUN TASKC 
TASKC BEGINS 
TASKC IS STOF 
TASK IS ALIV 


*ENT START 


ANT REQUESTS TASKED 
FING FOR EVENT FLAG 
E. AND RUNNING 


a 
bd 
“ 
¥ 


a 


9 


ANT 


Sy “A> “a> 


a 
¥ 
a 
Ld 
a 
9 


a 


y 


System macros 
Surrlied macros 


Event flas 


¥ 
Set the fleas to 


could he rerformed heres but in this 


RUNNING: ¢ Disrelay 
5 Meagcedcde 


allow 


TASKE to be unblocked 
Branch om directive oF. 


“<TASKE UNABLE TO SET EVENT FLAG? . 


lisrelay error messese 


and exit 


“TASKI. HAS SET THE EVENT FLAG ANI! 


Yiisrlay message 
Exit 


TASKD HAS SET THE EVENT FLAG ANID IS EXITING 
TASKC HAS BEEN UNSTOPPED AND WILL NOW EXIT 


Example 4-2 


IS EXITING> 


Synchronizing Tasks Using Event Flags 
(Sheet 2 of 2) 
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SEND/RECEIVE DIRECTIVES 


General Concepts 


The Send and Receive directives are used to transmit a 13. 
word block of data between tasks. The sequence of events iS as 
follows. 


1. A task issues a Send Data request, specifying a _ receiver 
task and a data buffer. 


2. The Executive copies the data buffer into a data packet in 
the dynamic storage region (DSR or pool). 


3. The Executive places the data packet FIFO 
(first-in-first-out) into the receive queue of the 
specified receiving task. 


4. Later, the receiving task issues a Receive Data request, 
specifying a data buffer. 


5. The Executive copies the data packet into the buffer 
specified by the receiving task. 


Directives 


Table 4-4 lists the Send Data directive and the various 
Receive Data directives. The differences among the Receive Data 
directives concern what happens if there are no data packets in 
the receiver's receive queue. 


All receive directives receive 15(1@) words, including’ the 
sender task name (in Radix-5@ format) plus the data. If no sender 
task is specified in a Receive Data directive, the first packet in 
the receive queue is dequeued, regardless of which task sent it. 
If a sender task is specified, only a packet sent by that task is 
dequeued. 
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Table 4-4 


The Send/Receive Data Directive 
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After the run, use ASTXS$S to exit from the AST routine. 
After exiting from the AST routine, the AST routine will be 
entered again if a new data packet is received. This continues 
until the task exits, or until receive data AST'sS are canceled, 
using the Specify Receive Data AST directive (SRDAS) with no AST 
routine specified. It is also possible to temporarily disable all 
AST recognition using the Disable AST Recognition directive 


(DSARS). 


In addition, you can use the task control directives for 
synchronization. Table 4-5 summarizes the various synchronization 
techniques which might be used. Keep in mind that a Receive Data 
directive (RCVDS$) causeS an error condition directive, which is 
inconsistent with task state (DSW = -8, IE.ITS) if there is no 
data packet in the receive queue. Receive Data or Stop (RCSTS) 
and Receive Data or Exit (RCVX$), on the other hand, cause the 
task to stop or exit, respectively, if there is no data queued. 
For further information about possible synchronization problems, 
see the writeup on the Receive Data directive (RCVDS$) in Chapter 5 
of the RSX-11M/M-PLUS Executive Reference Manual. 


Table 4-5 Methods of Synchronizing a Receiving Task 
(RECEIV) with a Sending Task (SEND) 
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Examples 4-3, 4-4, and 4-5 show the use of Send and Receive 
directives by a pair of tasks. Examples 4-3 and 4-4 use an event 
flag for synchronization; Example 4-5 uses Receive Data or Stop 
along with Unstop for synchronization. The notes below are keyed 
to Example 4-3. Note 1 refers to SEND1 and RECV1. Notes 5, 6 and 
7 refer to SEND1. Notes 2, 3, 4 and 8 refer to RECVI. 


@ RECV1 must be run first, or else the event flag will 
already be set by SEND1 to indicate that a data packet has 
been sent. RECV1 will clear the flag and wait for it to 
be set again, and won't realize that a data packet is 
already queued to it. 


Initialize the message counter. You will receive and 
display three messages and then exit. 


Initialize the event flag. 


Wait for the flag to be set after SEND1 sends the _ data 
packet, placing it in RECV1's receive queue. 


Get the data to be sent. 


Send the data and set event flag 33. when the data packet 
is queued to RECVI. 


SEND1 exits. 


Receive data from anyone. 


Display a header and the data sent. Skip the first two 
words (four bytes) of the buffer, which contain the name 
of the sender task in Radix-5@ format. 


Decrement the message counter. Branch back to clear’ the 
event flag and receive again if you have not yet received 
three messages. If you have, display a message and exit. 
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1 *TITLE RECVI 
2 *IDENT /0O17 
3 *ENABL LC y Enable lower case 
4 3 + 
2 § FILE RECVI.MAC 
& 7 
? § This task receives data from any sender task 
8 ¥ (@+sey GENDLO. It erints the data on TI?. Then it 
9 $$ waits for another date racket. It does this until it 
10 j has received 3 messases and then exits. 
11 r] 
12 § This task synchronizes with its sender through an 
13 5; event flag. 
14 3 
ia ? Assemble and task-build instructions? 
16 3 
17 3 MACRO/LIST LB? Cis LIFROGMACS/LIBRARYs dev: CufdRECVI 
18 } LINK/MAF RECVIsL&t Cl» LIPROGSUBS/LIBRARY 
19 3 
@ 20 y Install and run instructions? RECVI must be instelled 
al jo and rum before running SENT. 
mi *MCALL CLEFSCeWTSES$CeROVIGCYEXIT#&S §¢ Sustem macros 
24 *MCALL TYPE s DT RERR i Surrelied macros 
RS j 
2& EFN = 33, ¢ Event flas 
2? 3 
28 REUFF 3 eBLKW 1S. § Receive huffer 
a ; 
39 *ENARBL LSB y Enable local symbol 
Sil § blocks 
32 j 
C2) 33 START? MOV #39R5 § Initialize message 
34 > Counter 
© 35 AGAIN: CLEF¢C EFN § Initialize 
36 > suNMchronizins fla 
37 RCC WAIT * Branch on directive ok 
38 NIRERR ERROR INITIALIZING FLAGS $¢ Disrlay 
3? y error messade and exit 
(4 40 WAITS WYSE¢C  EFN ys Wait for a send 
4i BCC 3% y Branch om directive ok 
42 NIRERR <WAIT DIRECTIVE FATLEDS ¢ fisrelay error 
4S y Messade and exit 
44 * We set here when the flag is set 
rs) 43 S$ ROVEGC »R RUFF + Receive from anvone 
4G BCC 5 ¥ Kranch on directive ok 


Example 4-3 Synchronizing a Receiving Task Using Event Flags 
(Sheet 2 of 3) 


169 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


If a task runs and then exits with data packets in its 
receive queue, those unreceived data packets are flushed from the 
queue on exit. Therefore, if SEND1 sent four messages’ before 
RECV1 was run, the fourth message would be lost. 


If you want to run the tasks in Example 4-3 in any order, 
RECV1 must be modified to receive data packets on startup if SEND1 
has already sent data. The process gets complicated because SEND1 
may have already sent several data packets. It's also possible 
that event flag 33. was left set by someone else. In that case 
the Receive directive will fail, but you should not abort. 


Example 4-4 shows the modifications which must be made to 
Example 4-3 to allow the tasks to be run in any order. The 
following notes are keyed to Example 4-4. 


@ Use a flag word (BEFORE) to distinguish whether you are 
working on messages sent before or after RECV1 starts up. 
Note that RECV1S must be installed as RECV1, since SEND1 
sends to RECV1. 


@ Check to see if the event flag is set on startup. Tf. 2h 
is set, issue a Receive. If SEND] has been run one or 
more times, the Receive will succeed. If SEND1 has not 
yet been run, the flag was set by another task and the 
Receive will fail. 


© If the flag was not set, SEND1 hasn't sent any messages 
before you started. Clear the BEFORE flag, because a 
Receive failure after the flag is set again is a fatal 
error. 


4 | In the case of a receive failure, check to see if you are 
receiving data packets that are sent before RECV1 started 
up. If you are, you know you have received all data 
packets already queued up before RECV1 Started executing. 


@ If BEFORE is clear, there was a failure after receiving 


all data packets sent before RECV2 started up, so display 
an error message and exit. 
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1 *TITLE RECVIS 
2 eIQHUENT /O1/ 
3 *+ENABL LC § Enable lower case 


4 + 
hat § FILE RECViS.MAC 
& $ 
? § This task receives data from anv sender task 
3 ¢ Ce... SEND). It erints the data on TIt. Then it 
9 i waits for another date racket. It exits after 
160 > receiving and diselavying 3 messsses. 
11 ; 
12 > This task sumehronizves with its sender through an 
13 i event flas. Because of this sumchronizationsy and the 
14 > care we teke on startur to set messasdes slready 
15 > sembs the tasks can be run in anys orders with any 
146 i relative eriorities. 
1? 3 
18 i Assemble and teske-build instructions? 
Le 3 
20 } MACRO/SLIST LES CLs TIFPROGMACS/LIBRARY sdevilutfdJRECVULS 
21 } LINK/MAF RECVIS»yLBI CLs LIFROGSUBS/LIBRARY 
22 , 
23 i Install and run instructions: RECVIS must he installed 
24 i under the mame RECVI to work with SENT. 
25 fo 


2S *+MCALL CLEFECeWTSESC yROVIGCYEXITHS § Sustem macros 
27 *MCALL TYRE yTTRERR § Surrelied macros 


EN oss 3%, i Event flag 


"Before" flasds used to keer track of whether we ere 
TeceLlVing messases sent nefore RECVI started ur. If 
the event fleas is set at startur times keer receiving 


3 
EE 
3 
3 
3 
3 
bountal we get a failure. We then wait until the fles is 
3 

3 


3S get to receive adeainse 1 means receiving messages sent 
36 before starturs O means finished receiving them. 


37 BEFORE? WORT 1 y Assume there sre messases 
38 RBUFF 3 »BLIRW LS. Receive buffer 


“@> 


4Q *+ENABL LSE § Enable local symbol blocks 


42 START? MOV #F3yRS ’ Messase counter 

43 CLEF SC  EFN Y Initialize synchronizing 
s flas 

43 BCC 1% * Branch om directive ok 

4S QTIRERR <ERROR INITIALIZING FLAG? ¢ Diselay 

47 y error messase and exit 


Example 4-4 A Receiving Task Which Can be Run Before or After 
the Sender (Sheet 1 of 3) 
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Run Session 


>INS/TASK..NAMES RECVL RECVUIS 

RUN SENTDIN 

TYFE A LINE OF TEXTys 26 CHARACTERS OR LESS 
x hs 

SRUN SENDA 

TYFE A LINE OF TEXTs 2&6 CHARACTERS OR LESS 


Ce a 


Wes five Ave Bee fine Bee Aes Bos Ase dove 


“RUN RECV1 


naTA RECEIVED BY "RECVI"S 
pW Ge a ae fe 
NATA RECEIVED BY "RECVIS? 


2D OOOO IID 
toes Ane Bron Bose dove Bee Bee five Ase Aoe 


RUN SEND 
TYPE A LINE OF TEXT» 26 CHARACTERS OR LESS 


333533 


DATA RECEIVED BY "RECVI"$ 
33333 
“RECVI" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 


Example 4-4 A Receiving Task Which Can be Run Before or After 
the Sender (Sheet 3 of 3) 


Example 4-5 uses Receive Data or Stop in the Receiver and 
Send Data followed by Unstop in the sender. These tasks can be 
run in any order. The potential synchronization problems are 
considerably easier to deal with when using this technique of 
synchronization. The technique will be explained first as it 
applies to the case of running RECV2, before you run SEND2. A 
discussion of the other possibilities will follow. Notes 2, 3 and 
4 refer to SEND2. Notes 1, 5, 6, 7, 8 and 9 refer to RECV2. 


@ Issue a Receive Data or Stop directive. If there is no 
data packet queued, RECV2 stops and must be unstopped by 
SEND2. If, on the other hand, there is a data packet 
queued, you would want to receive it. The DSW equals 
IS.SET(+2) if the task was stopped and then unstopped, and 
equals IS.SUC(+l1) if a data packet was received. If RECV2 
is run first, stop. 


@ SEND2 gets the data and sends it. You do not need to 


specify an event flag in the Send Data directive since you 
use Stop/Unstop for synchronization. 
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If SEND2 is run two or three times before RECV2, any data 
packets already sent are received and displayed. In the case of 
two sent, the third RCDS$ will cause RECV2 to stop until SEND2 
sends a third packet and unstops it. In the case of three packets 
already sent, RECV2 will receive all three and then exit. 


As in Example 4-4, if SEND2 sends more than three _ packets, 
any additional packets will be lost because the receive queue is 
flushed when the task exits. 
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Sh “Gp “> “> “ap 


“Se “Mr Wr Sap “Sd CP EP “SS “SP “EP “> Sh ce “ED 


This 
the datay along with a headers om TI3. Then it waits 
for 
received 3 messages. 


This 
Because of this synchronizationy the tasks can be run . 
in ans orders with any relative rriorities. 


*TITLE RECV2 
@TQVENT /017 
*ENABL LC s Enable lower case 


FILE RECV2.MAC 


task receives date from another task. It evrints 


another date rackets continuing this until it has 


task synchronizes with its sender usins RCSTS. 


Assemble end task huild instructions? 


MACRO/LIST LER¢ Cl» LIPROGMACS/LIBRARY »devilCufdIRECVe 
LINK/MAFP RECV2»L Bi Cis LIPFROGSUBS/LIBRARY 


Install and run instructions: RECV2 must he installed. 


*MCALL RCST#CrRCOVDSCYEXTT$S § Sustem macros 


»MCALL TYFE»sTIRERR + Surrelied macros 
3 
RBUFF 3 +BRLRW 15. § Receive huffer 
§ 
*+ENABL LSE ¢ Enable local sumbol 
§ blocks 
START? MOV #3 9RS § Set ur messade counter 
RECEIV? RCOST&éC »RBUFF § Receive from anyone 
BCC a §’ Branch om directive ok 


QIRERR <RECEIVE DIRECTIVE FATLED IN "RECV2"> 
liselay error messade 
; and exit 


Successful receirt or unstorred bu another task. First 


“OS § 


Wo 


have to receive tne data 


; 
5 check for unstorred after being storreds im which case 
> 


CMF $OUSWy tI S.SET § Were we storred due to 
y no data 

BENE &$ i If moty we have a data 
; racket 

RCVOS$C »RBUFF § Now set the racket 


Se 


RCC &# Branch om directive ok 
QIRERR <RECEIVE DIR FAILED AFTER "RECVS" UNSTOFFED > 
§ Tigrelay error message 
§ and exit 


TYFE <QATA RECEIVER BY "RECV2"t> ¢ Tliselay 
y text and 

TYPE #REUFF +49 #26. * data sent 
SO RS»sRECEIYV + Necrement messase 

§’ counter. Receive again 

§ aif haven’t received 3 

y vet 
TYFE “"RECV2" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT> 


$ Tere exit messade 
EXIT#S § Exit 
+ENIt START 


Example 4-5 Synchronizing a Receiver Task Using RCDS$ 


(Sheet 2 of 3) 
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Using Send/Receive Directives for Synchronization 


If you want to pass data as well as notify another task of 
the occurrence of an event, the send/receive directives can be 
used to perform this double function. The receiving task can 
synchronize with the event using any of the techniques listed in 
Table 4-5. 


Slaving the Receiving Task 


Normally, a task runs under the UIC and the TI: of its 
initiator, the operator issuing the RUN command, or the task 
issuing the Request Task directive (RQST$). A receiver task which 
is run from the same terminal as the sender is assigned the same 
UIC and TI: as the sender. However, if the receiver task iS run 
from another terminal or by a different user, it's UIC and/or TI: 
may be different from that of the sender. Also, a receiver might 
receive data from several different tasks initiated at several 
different terminals. 


If you want to have the receiver task take on the UIC and the 
TI: of the sender each time data is received, the receiver task 
can be built as a slaved task. The advantages of this approach 
are that the receiver acquires the same privileges as the sending 
task and can do I/O directly to the sending task's terminal 
(through TI:). To build a task as a slaved task, either 
task-build or install with the /SLAVE qualifier. 
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PARENT 


SPAWN OFFSPRING COMMAND LINE . 


OFFSPRING 


EXIT, EXIT 


WITH STATUS, 
EVENT FLAG AND/OR 


OR EMIT 
AST ROUTINE OFFSPRING STATUS STATUS 


TK-7745 


Figure 4-1 Parent/Offspring Communication Facilities 


Additional directives are provided for parent/offspring 
Support. The Send Data, Request, and Connect directive combines 
the functions of the three separate directives (Send, Request, 
Connect) into a single directive. This is similar to Spawn, but 
sends a13. word data packet rather than a 79. byte command 
line. It also only sends data and connects if the task is already 
active. Spawn is rejected if the task is already active, unless 
the task is a Command Line Interpreter (CLI). 


Two other directives are provided to allow chaining, or 


passing a parent/offspring connection from an offspring to another 
task. Chaining is discussed in more detail later in this module. 
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Example 4-6 shows a task which spawns PIP to display a directory 


at: TI? 


The following notes are keyed to the example. 


The command line to be passed to PIP. We include the 
three-character command name to be consistent with the way MCR 
passes commands if a utility command is typed to MCR. 


Display startup message. 


Spawn ...PIP. Event flag 1 will be set when ...PIP exits or 
emits status. EXSTAT is the address of the eight-word status 
block (only the first word is’ used). CMD is the starting 
address of the command line and LEN is its length. 


Wait for event flag 1 to be set when ...PIP exits or emits 
status. Notice that this is a local event flag, local to this 
task, which is cleared by the Executive when the task is 
spawned and set by the Executive when the spawned task exits 
or emits status. 


The high order byte of the exit status code may contain 
unexpected data. Therefore, clear that byte before converting 
the code to signed decimal for display. 


Use SEDMSG to produce a status message. Display the message 
and then exit. 


ON THE RUN SESSION - The first run session shows a_ successful 
exit by ...PIP, the second one shows ...PIP aborted by an 
operator. Note the different status codes. 


NOTE 

On an RSX-11M system, an attempt to spawn 
--ePIP will fail if ...PIP is already active. 
This works diffently from initiating PIP from 
MCR, where an attempt is made to install the 
task ...PIP under the name PIPTnn if ...PIP 
is already active. A solution to this 
problem is to spawn CLI... (the current 
CLI), ...DCL (DCL) or MCR... (MCR) and send 
it the command line. It will in turn start 
up the appropriate PIP task under ...PIP or 
PIPTnn, as if the command was typed in by an 
operator. See section 4.4 (on Spawning 
System Tasks) of the RSX-11M/M-PLUS Executive 
Reference Manual for additional information. 
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33 s Error handling code ~- » Tliselay error message and exit 
54 ERRI0N3 DOTRERR <ERROR WRITING STARTUF MESSAGE> 

59 ERRII?3 IOERR #TOSB»<ERROR WRITING STARTUP TEXT> 

BG ERR? 3 QNIRERR <ERROR SPAWNING FIPS 

o7 ERR33 NIRERR <ERROR WAITING FOR EVENT FLAG> 

ue ERR403 DTRERR <ERROR WRITING FIF’S EXIT STATUS> 

89 ERR4I3 IOERR #TOSBy<ERROR WRITING FIF’S EXIT STATUS> 
40 «ENT START 


Rum Session 


“RUN SPAWN 
SFAWN IS STARTING ANI! WILL SPAWN PIF 


Ttirectory DBLICS0Ss 3014 
B-MAR-82 12315 


WeMAC EI 1. 20-MAY~-81 13:04 
AL.MACS2 1. O9-TNEC-80 16358 
A+MACS 1 1. 10-JUN-81 15321 
SPAWN. MAC $22 1. 08-SEP-81 11:20 


Total 127./129. blocks in 25. files 


- SFAUN REPORTING? FIF EXITED. EXIT STATUS WAS 1. 


“RUN SPAWN 
SFAWN IS STARTING ANID WILL SPAWN FIF 


Directory DRIIC30S» 3017 
8-MAR-82 12315 


WeMAC #1 1. 20-MAY-81 13204 
AL»MACS2 1. O9-TEC-80 16:58 
A»MAC $1 1. 10-JUN-81 15321 
NCLSABORT/TASK «++PIF 

AY.MACI12 4. 21-MAY-81 13250 


12215215 Task “..-PIF* terminated 
Aborted via directive or CLI 
And with rendinsg I/O reauests 


“SPAWN REPORTING? PIF EXITED. EXIT STATUS WAS 4. 


Example 4-6 A Task Which Spawns PIP (Sheet 2 of 2) 
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1 +TITLE GSFAWN 

2 IDENT /O1/7 

3 *+ENABL LC ; Enable lower case 

4 9+ 

5 5 FILE GSFAWN.MAC 

& 3 

7? § This task rromets at tit for a task name and command 

8 ’ liney then srawns the srecified task and rasses it the 
9 } command line. After that it waits until the offsrring 
10 § task exits and disrelays its exit status. 

il ; 

12 >; Assemble and task-build instructions? 

13 3 

14 5 MACRO/LIST LB? CisyLIFROGMACS/LIBRARY »devi lufdIGSFAWN 
15 3 LINK/MAFP GSFAWNsLBI Cis. IFROGSUBS/LIBRARY 

16 j 

17 § Rum instructions? The name of the task to he srawned 
18 > must be tyred in using all urrer case characters. 

19 $j 

20 *+MCALL SFWNSS*EXITSS»sEXSTH»oDIRSsWTSESC §¢ Sustem 
2il ; Macros 
22 +MCALL INFPUTs TYPEsQIRERR ¢ Surelied macros 
23 5 
24 * I/0 buffer ~- initialize first 6 bytes to blanks to rad 
wo § short task names 

Ee BRUFFER? .ASCII 7 vA 
27 + BLKE 74s 


28 TSKNAM? .BLKW 2 + Task name im RADSO 

29 ROME? EXST$ EX#SEV $ Tlirective for fatal 

30 * error 

Sil BUFF? +BLAW 80. ¢ Quteut buffer for exit 


32 + status disrlay 
33 FMT3 *ASCIZ /ANAZIOSTASK EXITED. STATUS WAS ZD.ZN/ 
34 +EVEN 
35 EXSTAT? .BLKW 8. § Status block 
36 3 
37 +ENABL LSE 
oe (3: START? TYFE TASK NAME? $ Diselay rromet 
39 INFUT #BUFFER» #80. > Get inrut Cbuffer addr 
40 y returned in RQ) 
4i RCC i$ § Branch on directive ok 
42 TYFE SINFUT FROM TI? FAILED: 
43 QIRS ROME § Fatal error 


Example 4-7 A Generalized Spawning Task (Sheet 1 of 3) 
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Rum Session 


“RUN GSFAWN 

TASK NAME? 

eee PTF 

COMMAND LINE €79 CHARACTERS OR LESS)? 
PIF &X.DIS/LI 


Lirectory DRBLCSOS» 4017 
88-SEP-81 15309 


FRIENDS .UTS $2 Le 1O-AUG-81 11313 
FRIENDSNL .OTS¢2 1. A1~-AUG-81 11342 


Total of 2.710. blocks in 2. files 


TASK EXITED. STATUS WAS 1. 


“RUN GSFAWN 

TASK NAME? 

Chl ees 

COMMAND LINE ¢€79 CHARACTERS OR LESS)? 
NIRECTORY *.MAC 


Nirectory DTBLIC3OSs 3013 
8-SEF-81 15210 


WeMACE IL Le 20-MAY-B1 13704 
AL.MAC#2 Le OF—TEC-80 16358 
A+MACEL le LO~-JUN-81 L5t21 
AP.MAC#12 4, 2i-MAY-81 13250 
FORMAT .MAC $34 be 21-AUG-81 11253 
FROGY MACE 1 Ls 30~JAN-81 142327 
FROGZ.MAC# 1 1. 30~JAN-81 14330 
RAY .MAC 1. 4. 3O0~-JAN-81 142339 
NCLZEABORT/TASK DIR 

PROGX.MACISG te 3O0~JAN-81 14242 
C.MAC#S on 21i-MAY-81 10301 
AZ+MACH2 Is 2i-MAY-81 10204 
T2.MACHI 1. 2il-MAY-81 10304 

Task “IRTII" terminated 
9 Aborted via directive or CLI 


And with rending [70 reauests 


TASK EXITED. STATUS WAS 4. 


Example 4-7 A Generalized Spawning Task (Sheet 3 of 3) 
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Chaining of Parent/Offspring Relationships 


An offspring can chain or pass on its’ parent/offspring 
connection to another task. In that case the connection between 
the parent and the offspring which passes the connection is 
broken. In its place, a connection is made between the parent and 
the new offspring. 


Figure 4-2 shows the difference between an offspring spawning 
another task versus chaining its connection to another task. Note 
that with Spawn, the connection between the parent and the _ first 
offspring still exists, and a new connection is established 
between the first offspring and the new offspring. 


Table 4-18 summarizes the directives which can be used to 
chain parent/offspring relationships. Request and Pass Offspring 
Information (RPOI$) is similar to Spawn in function, in that it 
starts up the task and can pass a 79. byte command line. Send 
Data, Request, and Pass Offspring Control Block (SDRP$) is similar 
to Send Data, Request and Connect, in that it sends a 13. word 
data packet, and executes successfully even if the task is already 
active. 


TASK 2 TASK 2 REQUESTS 
SPAWNS AND PASSES OFFSPRING 
TASK 3 INFORMATION 
BEFORE AFTER BEFORE AFTER 
TASK 1 TASK 1 TASK 1 


| 
| 
| 
| 
TASK 2 | TASK 2 TASK 3 
| 
| 
| 


| 
| 
| 
| 
task 2 || 
| 
| 
| 
| 
| 


NOTE: EACH ARROW SHOWS A PARENT/OFFSPRING CONNECTION. 
THE ARROW STARTS AT THE PARENT AND POINTS TO THE OFFSPRING. 


. TK-7746 


Figure 4-2 Spawning Versus Chaining 
(Request and Pass Offspring Information 
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The following notes are keyed to Example 4-8. 


@ Use RPOIS instead of SPWN$. No event flag is needed nor 
is a status block set up since this task won't receive 
status from ...PIP. RP.OAL specified means that all (in 
this example there is only one) parent connections are 
passed on. A connection is established between the parent 
of PASSIT (GSPAWN) and ...PIP. The connection between 
GSPAWN. and PASSIT is broken. 


@ Display a message and exit. You don't need to use $EDMSG 
because this task doesn't receive exit status. 


@® c:xit with a status of 18., to make it easy to tell whether 
the status is from this task or from ...PIP. Note in 
SPAWN that EXITSS is used, which results in a success code 
(+1) being sent as the exit status. 


@ 0n The First Run Session (GSPAWN spawns PASSIT) - The exit 
Status from ...PIP is returned directly to GSPAWN. 


@ 0n The Second Run Session (GSPAWN spawns SPAWN) - The exit 
Status from ...PIP is returned to SPAWN, then SPAWN 
returns its own exit status to GSPAWN. 


If you wish to chain the connection from only one of several 
parents, specify a single task, and do not specify RP.OAL in the 
RPOIS$ directive call. If RP.OAL is not specified and no task is 
specified, then no connections are passed. This might be useful > 
to request a task and send 79. bytes of data when a connection is 
not needed. 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


Rum Session 


SINS FASSIT 

RUN GSFAWN 

TASK NAME? 

FASSTT 

COMMAND LINE (€79 CHARACTERS OR LESS)? 


PASSIT IS STARTING AND WILL REQUEST FIF 
FASSIT HAS REQUESTED FIF ANDI WILL NOW EXIT 


Directory UBLIC30%? 301 
G=-MAR-B82 15122 


WeMAC EL 1. 20~-MAY-81 13304 
AL.MACS2 1. O9-NEC-80 16258 
SFPAWN.MAC #1 4. O8-SEF-81 13332 


Totel of 13./66. blocks in 15. files 


TASK EXITED. STATUS WAS 1. 


“RUN GSFAWN 

TASK NAME? 

FASSIT 

COMMAND LINE ¢€79 CHARACTERS OR LESS)? 


FASSIT IS STARTING AND WILL REQUEST FIP 
PASSIT HAS REQUESTED FIF AND WILL NOW EXIT 


Directory IBIC30% 301) 


8-SEFP-81 15223 

WeMACS 1 Le 2O-MAY81 13204 
AL.MACS2 1. OO-HEC-80 146758 
AeMACs 1 1. LO-JUN-84 LS3 24 
AY,MACF12 4. 21-MAY-83 13350 


L5224310 Task “"..-PIP" terminated 
Aborted vie directive or CLI 
And with vending I/O reauests 


TASK EXITED, STATUS WAS 4. 


Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 2 of 3) 
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Other Parent/Offspring Considerations 


Retrieving Command Lines in Spawned Tasks - Use the Get MCR 
Command Line directive (GMCRS$). The passed command is returned, 
beginning at offset G.MCRB within the DPB for the GMCRS directive. 
Therefore, if you use the $ form of the directive and if the DPB 
Starts at location DPBl, the first character of the command line 
is at location DPB1+G.MCRB. 


Spawning a Utility or other MCR Spawnable Task - Utilities are 
generally installed under task names of the form ...tsk. This 
makes them MCR spawnable tasks, which notifies MCR to spawn 
multiple copies of the task under names tskTnn if the task is 
invoked as an MCR command using the three-character task name 
(e.g., PIP /LI). 


Any task iS spawnable, but only tasks installed under a name 
of the form ...tsSk are spawned as multiple copy tasks by MCR. 
When such a task is invoked by MCR, MCR passes it the entire 
command line, including the three-character task name (e.g., 
PIP /LI). Even if you spawn a utility directly, you should pass a 
command line which includes the three-character task name. This 
maintains compatibility with the format used by MCR to pass 
commands to utilities, and avoids potential problems caused when 
the utility parses your command line. 


On RSX-11M systems, there is a greater chance of getting a 
task already active failure if you spawn a utility directly using 
the name ...tsk, than there is if you spawn MCR... and pass_ the 
command line which includes the task name. This is due to the 
fact that if a task is spawned directly using ...tsk, the spawn 
attempt fails if the task ...tsk is already active. No attempt is 
made to install the task under the name tskTnn if ...tsk is 


already active, as is the case if you spawn MCR... (MCR) to start 
up the utility. 
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ONA UM Pwr 
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USING 


~~ 


This 
line 


> > “> “Er “Go EP “CS “KP “tr 
. 


“S> “> ‘Sr “Se “OP “GP “CD 


8 
GMCR? 
BUFF? 
FMT 3 
IOSE?3 


LATAL 
NUMLE | 


NUM2? 
ANS! 
OF? 


a 
¥ 


Example 


DIRECTIVES FOR INTERTASK COMMUNICATION 


+TITLE SPWNED 
eIQENT /0O17 
*+ENABL LC 5 Enable lower case 


task uses the GMCRS cirective to set a command 
from either TI? or the rarent task. It then 


echoes the command Line and does an add or multirelyy 
tyres out the answer and emits status on exit 


Assemble and link instructions? 


MACRO/LIST LER¢ C1 sy LIPROGMACS/LIBRARY sdevs CufdISPWNEn 
LINK/MAF SFPWNEDeL BSC» LIFROGSUBS/L IBRARY 


Install and run instructions! To make this task MCR 
srawnableys install it under the mame «-+-SFW. Commands 
should be of the form SPW ome where m is a function. 

The valid funetions gre 1 (for add) and 2 (for multirly,. 


*+MCALL EXST#SeGMCRésDIR¢sQTOWSS §¢ Sustem macros 
*MCALL TYFE sDIRERRs TOERR ¢ Surerelied macros 


QER for Get MCR Command 
Line directive 

+ BLIKE BO. Qutreut buffer 

*ASCIZ /40 ZA “ZL = “Z2O./ §# Format string 


GMCRS 


Sr Sr “Sb 


+EVEN 

+ BLIKW 2 § I/0 status block 

»WORT 3 § ist orerand 

»WORD OF § address of oreration 
5 $ism im ASCIT 

*WORT 2 § 2nd orerand 

+ BLAW I §j answer to oreration 

+ BLIANE 1 § orerand im ASCII 

+EVEN 


4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 1 of 3) 
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Rum Session 


*INS/TASK.NAME?..+SPW SFWNET 
“MCR SPW 1 

SPW 1 

MCR SFW 2 

SPW 2 

3k 2 = 10. 

MCR SPU 3 

SFU 3 

© NO OTHER OPERATIONS ALLOQWETD 


“RUN GSPAWN 

TASK NAME? 

7+ SPU 

COMMAND LINE ¢79 CHARACTERS OR LESS)? 
SPW 1 

SFW i 


oS - 2 = 7. 


TASK EXITED. STATUS WAS 1. 
“RUN GSFAWN 
TASK NAMIE? 
0+ + SPW 
COMMAND LINE ¢€79 CHARACTERS OR LESS)? 


SPW 2 
SPW 2 
S k.2 = 104 


TASK EXITED. STATUS WAS 1. 


~@ | run csrawn 


TASK NAME? 
76 SEW 
COMMANT LINE ¢€79 CHARACTERS OR LESS)? 
SPW 3 
SFW 3 
NO OTHER OPERATIONS ALLOWET 


TASK EXITEN. STATUS WAS 0. 


Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 3 of 3) 
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Task Abort Status Codes 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 
Table 4-11 
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Other Methods of Transferring or Sharing Data Between Tasks 


If large amounts of data are to be transferred between tasks 
or shared between tasks, two other techniques are available. 
Tasks can use files on mass storage devices. This technique is 
advantageous if really quick transfer is not essential and/or if a 
permanent copy of the data is needed. 


Tasks can also be written to share a data area in memory. 
This technique is particularly useful if transfer time is critical 
and a permanent copy of the data is either not needed at all or is 
not needed until a later time. Both of these techniques are 
discussed in later modules. 


Now do the tests/exercises' for this module in the 
Test/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either in that book or 
on-line files. 


If you think that you have mastered the material, ask your 
course administrator to record your’ progress in your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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MEMORY MANAGEMENT CONCEPTS 


INTRODUCTION 


The use of memory management hardware in mapped systems 
permits the use of more physical memory, task relocation, and the 
sharing of data and code. It also offers a memory protection 
feature. This module explains how the memory management hardware 
works and how the software interacts with the hardware. Later 
modules explain the use of memory management for overlays and 
shared regions. 


OBJECTIVES 


1. To list the differences between mapped and unmapped 
systems 


2. To list the advantages of memory management 


3. To use virtual and physical addresses, windows, and 
regions to describe the mapping of a task. 


RESOURCES 


1. RSX-11M/M-PLUS Task Builder Manual, Chapter 2 


2. PDP-11 Processor Handbook, Chapter 6 (optional) 
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GOALS OF MEMORY MANAGEMENT 


The KT-1l memory management unit is a device available on 
medium and larger PDP-1ll's. While the 16-bit addressing structure 
of the PDP-1l's limits processors without a memory management unit 
to 32K words of addressing, processors with a memory management 
unit can support up to 128K words, or even as much as 2@@@K words 
(2 Meg words), depending on the model of the processor. 


In addition to this extension of the processor's addressing 
space, a memory management unit offers other features. not 
otherwise available. With memory management, tasks can be loaded 
and executed at different locations in memory without being 
modified in any way. This means that the operating system can 
load a task into any available space within a system-controlled 
partition; therefore a task need not wait until a specific 
location is available. It also means that the Executive can move 
tasks around to make better use of available space (shuffling). 


Memory management also provides a mechanism for controlling 
tasks' access to memory. Memory areaS can be protected: 
unrelated tasks can reside in memory simultaneously and are 
normally prevented from accessing each other's memory. However, 
tasks which do need to share memory locations are allowed to _ do 
so, under the rules of memory access built into the Executive. 


HARDWARE CONCEPTS 


Mapped Versus Unmapped Systems 


A system which has the KT-11 memory management unit installed 
and enabled is called a mapped system. Otherwise, it is called an 
unmapped system. Small PDP-ll's, such as the PDP-11/83 and 
PDP-11/04 are always unmapped. The KT-11l unit is available as an 
option on some medium sized processors, including the PDP-11/35 
and PDP-11/4@. It is a standard feature on large and newer 
processors such as the PDP-11/76, PDP-11/24, PDP-11/23-PLUS and 
PDP-11/44. 


Table 5-1 shows a comparison of unmapped and mapped systems 
on various PDP-1ll's. 
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Figure 5-3 shows the layout of a mapped system with 22-bit 
addressing. Twenty-two bits give an addressing limit of 248K 
words or 4896K bytes. Again, the top 4K words correspond to the 
I/O page. 124K words are used for UNIBUS mapping, which is needed 
when peripheral devices access memory directly (DMA devices). 
UNIBUS mapping is necessary to convert an 18-bit UNIBUS address to 
22-bit physical memory addresses. This leaves 1920K words of 
physical memory. Again, the Executive, including POOL, usually 
takes 16K words or 20K words, leaving 1984K words or 19@@K words 
for tasks. | 


PHYSICAL 
ADDRESSES 
(IN OCTAL) 
177777 
4K WORDS 1/O PAGE 
160000 
157777 
32K WORDS 
(28-N)K WORDS OF ADDRESSING 
28K WORDS 
OF 
MEMORY 
N K WORDS 
(N<20) EXECUTIVE 


TK+7747 


Figure 5-1 Physical Address Space in an Unmapped System 
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PHYSICAL 
ADDRESSES 
(IN OCTAL) 
17777777 
4K WORDS 1/0 PAGE 
17760000 
17757777 
RESERVED 
124K WORDS 
(UNIBUS MAP) 
17000000 
16777777 
2048K WORDS 
1920K scout OF ADDRESSING 
WORDS OF 1900K WORDS 
MEMORY 
16K OR 20K 
WORDS EXECUTIVE 
0 


TK-7758 


Figure 5-3 Physical Address Space in a 22-Bit Mapped System 
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On a mapped system, the Task Builder fixes a task'S code in 
virtual address space, but the actual mapping of virtual addresses 
to physical addresses is performed at run time by the memory 
Management unit. Tasks may be loaded at different physical 
addresses and still run correctly. As you will see later, mapping 
also allows a task to access several separate pieces of physical 
memory. 


PHYSICAL PHYSICAL 


ADDRESSES 
MEMORY (IN OCTAL) 
VIRTUAL VIRTUAL 
ADDRESSES 
(IN OCTAL) MEMORY 
140000 
137777 137777 
TASK TASK 
8K WORDS 8K WORDS 


100000 
77777 


100000 


EXECUTIVE 
16K WORDS 


TK-7759 


Figure 5-4 Virtual Addresses Versus Physical Address 
on an Unmapped System 
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MEMORY MANAGEMENT CONCEPTS 


The KT-11 Memory Management Unit 


Mode Bits - Bit 15 and 14 and bits 13 and 12 of the _ processor 
status word (PSW) indicate, respectively, the current and previous 
modes of processor operation. The mode may be: 


e Kernel mode (@@) 
e User mode (11) 


e Supervisor mode (@1). (Supervisor mode is not used on 
RSX-11M, and is available only on 11/45, 11/55, 11/44, and 
11/79.) 


The purpose of having different processor modes is to provide 
for a privileged mode (kernel) where the Executive can execute 
privileged instructions (e.g., HALT) , and can manipulate 
privileged locations (e.g., PSW), and a non-privileged and 
protected mode (user) where tasks usually execute. 


Active Page Registers (APRs) - The Active Page Registers (APR's) 
in the KT-1l1 memory management unit are used to define the mapping 
or correspondence between virtual and physical addresses. On an 
RSX-11M system, one set of eight APRs is used at a time to define 
this mapping. There is one set of APR's used for each processor 
mode; one is used in user mode and another set is used in kernel 
mode. 


At any given time, the set of APRs in use is determined by 
the mode bits in the processor status word. Each APR in the set 
in use maps a specific range of virtual addresses, as shown in 
Table 5-2. The APR can map zero words, if not in use, up to the 
full 4K words, always in even multiples of 32 words. In 
actuality, the hardware may contain additional sets of APRs, but 
they are not used under RSX-11M. 


Each APR consists of two 16-bit registers, a page address 
register (PAR) and ae page descriptor register (PDR). The page 
address register contains a base address used in mapping’ the 
appropriate range of virtual addresses. 
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All virtual addresses within the main task area are mapped to 


PHYSICAL paYSICA 


MEMORY ADDRESSES 
(IN OCTAL) 


visi VIRTUAL 
ADDRESSES MEMORY PAR 


(IN OCTAL) _At 
Es 


160000 


1532200 
140000 £ 


120000 F 


100000 £ 
70000 
60000 


512400 
40000 


472400 
20000 


452400 
0 


432400 


TK-7761 


Figure 5-6 Page Address Registers Used in Mapping a Task 
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physical addresses beginning at location 99432490(8). This means 
in effect that each virtual address corresponds to an offset 
location G@GV4324006 (8). The page descriptor registers, 
illustrated, indicate that APRs @, 1, and 2 map 4K words each, but 
that APR 3 maps only 2K words. 


from 


not 


MEMORY MANAGEMENT CONCEPTS 


In easier terms, virtual address 49000(8) will be located at 
the base physical address. A virtual address 13422(8) bytes above 
that will be 13422(8) bytes above that physical location. The 
base physical address is determined by converting the block number 
in APR2, 9@4724(8), to the physical address 9@04724@08(8). (Recall 
that a block of memory is 180(8) bytes.) Therefore, address 
953422(8) is mapped to the location shown below. 


98472490(8) Base physical address 
+ 13422(8) Displacement 


99586822 (8) Actual physical address 


Example 2 


Convert the virtual address 165275(8) 


$------- $------------------- ---- + + 
165275(8) = |/112311{/10@641804180d412¢6d1dat1161( (2) 
$------- $----~----------------- + 
7 05275 (8) 
APR Offset 


APR 7 = @15322(8) blocks = @1532200(8) Base physical address 
+ 95275(8) Displacement 


G1537475(8) Actual physical address 


The memory management unit performs this conversion using an 
adder and a number of internal registers. The conversion is 
performed at extremely fast speeds. Chapter 6 of the 
PDP-11 Processor Handbook discusses this conversion process in 
more detail. 
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Memory management directives can be used to create and 
initialize additional windows while a task executes. Space for 
these additional windows must be allocated in the task header at 
task-build time, using the "WNDWS" option. Memory management 
directives and their use are discussed in Module 8 on Dynamic 
Regions. 


Regions 


A region is a contiguous area of physical memory to which a 
task may get access rights. A region must be contained completely 
within a partition. It can be part of a partition or the entire 
partition. 


There are three types of regions in an RSX-11M system. 


1. Task region - an area in a user-controlled partition or a 
system-controlled partition into which a task is loaded 
and then executes. 


2. Static Common Region - an area in a common type partition; 
e.g.-, a shared common for data or a shared library for 
code. 


3. Dynamic Region —- an area in a system-controlled partition 
which is created dynamically, at run time, using the 
memory management directives. 


A task gets access rights to a region by "attaching" to’ the 
region. Before the Executive attaches a task to a region, it 
checks its needed access against the protection on the region. 
This is similar to checking file protection before allowing file 
access. If the task passes the check on access rights, then the 
Executive attaches the task to the region by establishing a 
connection between the two. The total amount of physical memory, 
made up of regions, to which a task is attached is called a task's 
logical address space. 


After a task is attached to a region, it actually accesses or 
uses the region by first "mapping" one of its virtual address 
windows to a part or to all of the region. During this process, 
the Executive uses the window and region information to fill in 
the APRs. After this, references in the task to virtual addresses 
in that window map to physical addresses within the region. A 
region does not have to be the same size as a_ window. Generally 
it is of equal or larger size than the window. 
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PHYSICAL PHYSICAL 


(IN OCTAL) 


a 


1476400 
VIRTUAL VIRTUAL / 
ADDRESSES PAR 
(IN OCTAL) MEMORY APR VALUE // 
177777 
WINDOW COMMON 
2 166006 IE a UU, ee 
YUN SEDF 605600 
WINDOW § 147777 014764 
140000 | LIBRARY (2K WORDS) | rn 
000000 
120000 
UNUSED ieee 
100000 
006232 
63777 
60000 
006032 
40000 
wINDOW 
0 (13K WORDS) 005632 ona 
aa REGION 
005432 
0 
543200 


Figure 5-7 A Task with Three Windows Mapped to Three Regions 
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OVERLAYS 


INTRODUCTION 


Overlays are used to allow a task to be developed and run if 
there is not enough available physical or virtual memory for a 
task. This module explains the various overlay techniques and how 
to use them. 


OBJECTIVES 


1. To determine whether to use a disk-resident or 
memory-resident overlay in a given situation 


2. To construct overlay structures using the overlay 
descriptor language 


3. To write tasks uSing overlays. 


RESOURCE 


e RSX-11M/M-PLUS Task Builder Manual, Chapters 3 and 4 
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CONCEPTS 


A task may be too large to fit in the available memory. This 
may happen because it is larger than the total amount of memory on 
the system. More likely, it is because the task is larger than 
the partition it is to run in, or the available space within the 
partition. The partition is probably used by other tasks at’ the 
same time; therefore, the available space may be considerably 
less than the full partition. | | 


For example, a 2@K word task may have to fit in 15K words of 
memory. The task can use overlays and load only portions of the 
code at a time, and use just 15K words of memory. 


Typically, the pieces which overlay each other contain 
subroutines. AS an example, consider a task with main code and 
two subroutines, G and H, which overlay each other. The main code 
calls subroutine G first, causing G's code to be read into memory. 
Later, the main code calls subroutine H, causing H's code to be 
read into the same memory locations, overlaying subroutine G. If 
the main code later calls G, G's code overlays subroutine H. As 
the task executes, overlaying is performed whenever necessary. 
You can choose to have all loading of overlay segments done 
automatically, or you can load them manually with specific calls 
to a loading routine. ; 

In addition to physical memory limitations, tasks on PDP-11 
systems have virtual memory limitations. As discussed in the last 
module, a task can only use a maximum of 32K words of virtual 
addresses at a time. A task may require more than 32K words of 
physical and also virtual memory. For example, a task may need 
4QK words of physical memory, exceeding the virtual addressing 
limit. This means that the task can't address all of its code. 
Overlays loaded from disk permit this task to run in 32K words or 
less of physical memory, and allow all of the code loaded at any 
given time to be addressed. Therefore, 32K words of code or less 
are loaded and addressed at any one time, satisfying the virtual 
address limit. 


Another method is to use special kinds of overlays. With 
these, all 4@K words of code can be loaded into memory, but the 
task maps only 32K words of code at a time. This means’ that’ the 
task stays within the virtual addressing limits even though it 
uses 4@K words of physical memory. 


These special kinds of overlays are called memory-resident 


overlays. They overlay by remapping, rather than reloading, code 
into memory. 
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Main Segment: PROG 

PROG calls: SUB1, SUB2, SUB3 

SUB1 calls: A, B 

SUB2 calls: none 

SUB3 calls: C, Dy E 
Size 

Segment in Words 

PROG . 4K 

SUB1 2K 

SUB 2 3K 

SUB 3 1K 

A 1K 

B 2K 

c 1K 

D 2K 

E 1K 

Total 17K 


Example 6-1 Description of an Overlaid Task 
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STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS 


Use the following steps to develop a task which uses 
overlays. 


1. Assemble each module, producing an .OBJ file for each 


2. Use the editor to create an overlay descriptor file 
(defines the overlay structure for the Task Builder). 


3. Task-build using the overlay descriptor file as the input 
file. 


THE OVERLAY DESCRIPTOR LANGUAGE (ODL) 


The overlay descriptor language (ODL) is a fairly simple 
language which is used to define the overlay structure for the 
Task Builder. Statements are placed in a text file which has a 
file type 'ODL' (e.g., EXAMPLE.ODL). This text file is identified 
to the Task Builder as a special file by using the 
/OVERLAY DESCRIPTION input file qualifier (/MP in MCR) in the 
task-build command line. 


ODL Command Line Format 


The ODL command lines use the format that follows. 
label: directive argument-list ;comment 
where: 


label - A one- to six-character symbolic, required only 
on an .FCTR directive. 


directive - one of the following: 
-ROOT - indicates the start of the overlay tree 
- END - indicates the end of input 
-FCTR - allows naming of subtrees 
-NAME - allows naming a segment and assigning 
attributes 
-PSECT - allows special placement of a global 


program section (Psect). 
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Examples of ODL 


oe 


X, the root of a task, calls subroutines Y and Z. 


» END 


Explanation: xX is the root segment, Y and 2Z are each 


overlay segments. Virtual addresses are asSigned to X 
first. Starting after that, Y and Z begin at the same 
virtual address. Either Yor Z (never both) is loaded 


and mapped using those virtual addresses. 


Using the information from Example 1, Y calls subroutines 
U and V. 


Explanation: Add to Example 1. U and V are overlay 
segments which overlay each other. After the last 
address for Y, virtual addresses begin for U and Vv. 
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TYPES OF OVERLAYS 


There are two types of overlays available, disk-resident 
overlays and memory-resident overlays. In fact, both are loaded 
from disk. The distinction is that disk-resident overlays are 
loaded from disk every time they are needed, while 
memory-resident overlays are loaded from disk only the first time 
they are needed. After that, they remain in memory and remapping 
is used to overlay segments as needed. 


Disk-Resident 


Disk-resident overlays are available on all RSX-11M systems. 
An example of a task with a root segment and three disk-resident 
‘overlays is shown in Figure 6-3. 


On initial load, only the root segment MAIN is’ loaded. 
Overlay segments are loaded from disk whenever required. This 
typically occurs when a subroutine in the segment is called. So 
if the root segment MAIN contains a call for subroutine A, for 
example, segment A is loaded from disk prior to the transfer of 
control to A. 


If, after the subroutine returns control to MAIN, a call is 
made to subroutine B, segment B is loaded into memory right over 
segment A. If a call is later made to subroutine C, segment C is 
loaded right over segment B. This loading of overlay segments is 
performed whenever necessary. The subroutines may be called in 
any order, and each subroutine may be called any number of times 
in the course of task execution, 


The same starting virtual address is assigned to all three 
overlay segments, A, B, and C, beginning at the next 32(198) word 
boundary after the code for MAIN. So A, B, ’and C use the same 
virtual addresses and are loaded starting at the same physical 
address. One virtual address window maps the entire task; just 
the code in memory is changed when an overlay is loaded. 


This technique is useful when the entire task is too large 
to fit into the space allowed for it. In the example in Figure 
6-3, a 22K word task runs in 15K words of physical memory. 
Disk-resident overlays are the default overlay type. The ODL 
examples in the previous section all produce disk-resident 
overlays. 
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Memory-Resident 


Memory-resident overlayS are available only on mapped 
systems which support the memory management directives. Figure 
6-4 shows the same task as in Figure 6-3, this time with 


memory-resident overlays. On initial load, again only the root 
segment MAIN is loaded. The first time an overlay segment is 
needed it is loaded from disk. However, once a segment is 


loaded, it remains in memory and is not reloaded from disk. 


If subroutine A is called first, overlay segment A is loaded 
and virtual address window 1 iS mapped to A. If, after the 
subroutine returns control to MAIN, a call is made to subroutine 
B, then segment B is loaded, but not directly over A. Instead, 
it is loaded into another area of memory, and then virtual 
address window 1 is mapped to B. If a call is later made to 
subroutine C, segment C is loaded into another area of memory, 
and virtual address window 1 is mapped to C. 


The real gain in run time efficiency is made when an overlay 
is needed again. If another call is made to A, overlay segment A 
does not have to be loaded again from disk. It is already 
memory-resident. Therefore, virtual address window 1] is simply 
remapped from segment C to segment A. Any additional overlaying 
is performed by remapping, with no further loading of overlay 
segments necessary. Again, the subroutines may be called in any 
order and each subroutine may be called any number of times. 


The advantage of this approach is that after the first load, 
it is much faster than using disk-resident overlays. However, 
there are no savings in the use of physical memory. In fact, a 
bit more memory is required than with a non-overlaid task. So 
the main use of memory-resident overlays is for overcoming the 
32K word virtual address limit when execution time efficiency is 
important. A 44K word task can uSe memory-resident overlays if 
there is enough memory available and the time necessary for 
loading disk-resident overlay segments is unacceptable. 


The root segment uses one window, plus each overlay area 
requires a separate window. That means that virtual addresses 
for each overlay segment begin at the starting virtual address 
for the next highest APR, corresponding to a 4K word boundary. 
Notice that A, B, and C all begin at virtual address 69909(8), 
for APR3, because MAIN is 9K words long. MAIN uses all 4K words 
in APRS @ and 1, plus 1K word in APR2 (virtual addresses 49090(8) 
through 43777(8)). 
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PHYSICAL 
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Figure 6-4 An Example of Memory-Resident Overlays 
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LOADING METHODS 


There are two loading methods, autoload and manual load. 
With autoload, any necessary loading and/or remapping (in the 
case of memory-resident overlays) is done automatically and is 
transparent to the program. With manual load, the overlay 
segments are loaded by specific user calls to a loading routine. 
Autoload and manual load cannot be mixed in the same task. 


Autoload 


When a call is made to a subroutine in an overlay segment, 
an autoload routine takes control before the transfer to the 
subroutine is made. It checks to find out whether the required 
segment is already loaded, or loaded and mapped. It performs any 
necessary loading and/or remapping. After that, the transfer to 
the called subroutine is made. 


Autoload is path loading, meaning that ali segments’ along 
the path to the required overlay segment are loaded. For 
example, in example 2 in the previous section, with root xX and 
subroutines Y, U, V, and Z, if a call from segment X is made to 
subroutine U, both Y and U are loaded. Note that autoload loads 
only overlay segments along the path which are not already 
loaded. 


Autoload is indicated by an asterisk (*) before an _ overlay 
specification in an ODL line. An asterisk outside a set of 
parentheses applies to all levels inside the parentheses. 


The advantages of autoload are that it is easy to use and 
does not require changes in the source code. One disadvantage is 
that it increases the size of the segments because the autoload 
code plus its data structures must be included in the task. 
Another is that it executes slower than manual load, because the 
autoload code has_ to check for whether the required segment is 
available or not each time an autoloadable segment is called. In 
addition, autoload must be performed synchronously. See section 
4.1 on Autoload in the RSX-11M/M-PLUS Task Builder Manual for 
more information. 
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Manual Load 


With manual load, you must call the subroutine $LOAD to load 
and/or map any required overlay segment before calling a 
subroutine in that segment. You must also keep track of which 
segments are currently available, to avoid a transfer of control 
to an incorrect segment and to avoid unnecessary calis to. the 
loading subroutine. Manual load is not path loading. In Example 
2 of the previous section, if xX calls U, it can load just segment 
U, without loading segment y, unless it is desirable to load 
both. See section 4.2 on Manual Load in the 
RSX-11M/M-PLUS Task Builder Manual for more information. 


Manual load is the default loading method. Whenever’ there 
are no asterisks (*) in an ODL file, manual load is used. 


The advantages of using manual load are that it results’ in 
smaller overlay segments, is usually more run time efficient, and 
overlay segments can _ be loaded either synchronously or 
asynchronously. The disadvantages are that you must keep track 
of which overlay segments are loaded and use special code in the 
source program. 


Comparison of a Task With No Overlays, to One With Disk-Resident 
Overlays, and One With Memory-Resident Overlays 

Example 6-1, Shown earlier in the module, and repeated below 
for convenience, showS a main program which calls a subroutine, 


which in turn calls another subroutine, etc. Note that the sizes 
Shown for the various parts of the task are only approximate. 
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Task-build command: 


LINK/MAP PROG,SUB1, 


Fartition name 
Identification 
Task UIC : 
Stack. limits? 
PRG xfr address? 


OVERLAYS 


A,B,SUB2,SUB3,C,D,E 


Ol 

C3059 301] 

000254 001253 001000 OO51R2. 
021254 


Total address windows? 1. 

Task image sive ¢ 17792. words 

Task address limits? 000000 105357 

R-W disk blk limits? 000002 000107 OO0O106 00070. 
XXX ROOT SEGMENT? FROG 


> 
+ 


R/W mem limits 
Ylisk blk limits? 


Example 6-2 


000000 105357 105360 35568, 
000002 900107 000106 00070. 


Map File of Example 6-1 Without Overlays 
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PROG.ODL file: 


-ROOT PROG-*(SUB1-(A,B) ,SUB2,SUB3-(C,D,E) ) 
- END 


Task—-build command: 


LINK/MAP PROG/OVERLAY DESCRIPTION 


Fartition mame ~ GEN 

Identification = O1 

Task UIC $ C30S%S3017 

Stack. limits? 000260 001257 001000 OOS12. 

FRG xfr address  O21260 

Total address windows? 1. 

Task image size + 8800. words 

Task address limits? 000000 042237 
R-W disk blk limits? 000002 000120 000117 00079. 


EX63.TSK Overlay descriretion? 


Example 6-3 


Rase Tor Length 

G00000 O22177 O22200 09344. FROG 

022200 032233 010034 04124. SUBL 
032234 036237 004004 oO2052, A 
032234 042237 010004 04100. & 
022200 036203 014004 06148. SURBR2 
022200 026247 004050 02088. SUBS 
026250 032253 004004 62052. C 
026250 03625 010004 04100. i] 
026250 032253 004004 O2052. E 


Map 


File of Example 6-1 With Disk-Resident Overlays 
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PROG.ODL file: 


-ROOT PROG-*! (SUB1-!(A,B) ,SUB2,SUB3-!(C,D,E) ) 
- END 


Task-build command: 


LINK/MAP PROG/OVERLAY DESCRIPTION 


Fartition mame ¢ GEN 

Identification ¢ O1 

Task UTC 3 £305%3012 

Stack. Limits? 000320 001317 001000 OOS12. 
FRG xfr address? 021320 


Total address windows: 3. 

Task imade size ~? 18464. words 

Task address limits? 000000 077777 

Re-W disk blk limits? 000003 000122 000120 00080. 


EXDOVR.TSK Overlay descrirtion? 


Example 6-4 


Base Tor Lenasth 

000000 023077 O23100 O9792. FROG 

040000 O580077 oO10100 04140. SUBL 
060000 064077 004100 O2112. A 
060000 070077 O10100 04160. & 
040000 0354077 014100 06208. SUB? 
040000 644077 004100 O2112. SUBS 
060000 064077 O04100 O2112. C 
060000 070077 010100 04160. sf] 
060000 064077 004100 O2112. E 


Map 


File of Example 6-1 
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Comparison of Overlaying Methods (Cont) 


Table 6-1 
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In addition 


Table 6-1 compares the three overlaying methods. 
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Include needed modules from FOROTS.OLB in the root segment 
in segment A, and in segment B. You should specify the 
library in each segment which may need it. Otherwise, if 
segment A needs a library module not already included for 
the root segment, the library is not searched again for 
module A. 


An Overlay Example 

Example 6-5 is a simple task with a root segment ROOT and two 
overlay segments, P and Q. The following calling sequence is used 
during the execution of the task. 

ROOT calls P 

ROOT calls Q 

Figure 6-5 shows an overlay tree and a memory allocation 
diagram for this task. 

The code for Example 6-5 is separated into three different 
modules, one for each segment. The source file for the root 
segment ROOT contains the startup code and controls the overlay 


loading by calls to the subroutines. The source file for each 
overlay segment, P and Q, contains the subroutine code. 


OVERLAY TREE 


MEMORY ALLOCATION DIAGRAM 


ROOT ROOT 


TK-7755 


Figure 6-5 Task With Two Overlay Segments 
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The notes below are keyed to Example 6-5. 
@ on initial load only the root segment ROOT is loaded. 


@ with autoload, the call to subroutine P causes the 
autoload routine to load overlay segment P from disk, and 
then transfer control to the subroutine. 


3) Subroutine P displays a message and returns. 


The call to subroutine Q causes the autoload routine to 
load overlay segment Q from disk over segment P, and then 
transfer control to the subroutine. 


@ subroutine Q displays a message and returns. 


If another call were added to subroutine Q, the autoload 
routine would check to make sure that overlay segment Q is already 
loaded, and would then transfer control to Q. If another call 
were added to subroutine P, the autoload routine would check and 
find that overlay segment P is not loaded. It would then _ load 
segment P over segment Q and transfer control. 


To use manual load, use additional code to load the segments 
into the root segment ROOT. Also, modify the .ODL file, omitting 
the asterisk (*). The files MLROOT.MAC and MLEXDOVR.ODL on_ the 
tape provided with this course are modifications of ROOT.MAC and 
EXDOVR.ODL for manual load. Check UFD [2@2,3] for these files. 
See your course administrator if you have difficulty finding them. 
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t TITLE Q 

2 +IQENT /0147 

3 *ENABL. LC i Enable Lower case 

4 $+ 

ba > FILE Q.MAC 

& 3 

7 + This subroutine disrlays 3 messaste and returns. 

8 oo 

9 *+MCALL QIOWSC i External sustem macras 

10 3 

11 MES 3 *ASCIT /SEGMENT Q IS NOW LOADED. SUBROUTINE Q/ 

12 *ASCIT / IS EXECUTING./ 

13 LMES = .-- MES 

14 + EVEN § Move to word boundary 

15 3 

16 Qi3 QIOWSC TO.WVERy Seles ye iMESesLMES»40> ¢ Ttiselay 
is] [37 y MeESSadte 

18 RETURN § Return 

19 «ENT 


Run Session 


RUN EXDOVR 

THE MAIN SEGMENT IS RUNNING ANID WILL CALL F. 
SEGMENT F IS NOW LOADED. SUBROUTINE F IS EXECUTING. 
THE MAIN SEGMENT WILL NOW CALL Q. 

SEGMENT Q IS NOW LOADER. SUBROUTINE & IS EXECUTING. 
THE MAIN SEGMENT WILL NOW EXIT. 


Example 6-5 A Task With Two Overlay Segments (Sheet 2 of 
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Subroutine Calls 


With manual load, since the global symbols are _ resolved 
directly to the virtual address corresponding to the symbol, the 
transfer is directly to the subroutine. The program must ensure 
that the correct overlay segment is loaded before making the call. 
Otherwise, the transfer will transfer control to that virtual 
address in the wrong code, causing unexpected results. 


With autoload, the global symbols are resolved directly for 
calls downward toward the root. This works because path loading 
ensures that the segments along the path closer to the root are in 
fact loaded. The calls to subroutines away from the root are 
resolved through autoload vectors. This causes the call to the 
subroutine to transfer control first to the autoload routine, 
allowing it to check and load any needed overlay segments’ before 
transferring control to the virtual address of the subroutine. 


Data References 


The safest place for all data is in the root segment. Data 
placed in an overlay segment is only accessible when the overlay 
segment is loaded and the reference is resolved directly. This 


means that with manual load, the data is accessible when the 
segment is loaded. 


With autoload, on the other hand, it's not that’ simple. 
References out from the root are usually not resolved directly, 
but through autoload vectors. For example, the reference to the 
global symbol A, a data label, is resolved to the label of an 
autoload vector within the same overlay segment. The actual 
virtual address of A is a value within the autoload vector. 
Therefore, a reference to A references the autoload vector, not 
the data itself. In addition, a reference to A does not cause the 
overlay segment to be loaded. It is loaded only on a call to a 
subroutine. Although there are some ways with autoload to get 
references resolved directly, it is difficult. 


With disk-resident overlays, another problem arises with any 
data changed at run time. If the data is in an overlay segment, 
it is reinitialized every time the segment is reloaded from disk, 
since the original copy of the code is reloaded. This problem 
occurs with both manual load and autoload. 
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The Task Builder normally combines together allocations’ for 
Psects of the same name. If the Psects have the local (LCL) 
attribute, combining is only done within a single overlay segment. 
If the Psects have the global (GBL) attribute, combining is done 
across overlay segment boundaries. For Ppsects with the GBL 
attribute, by default, these allocations are collected in the 
segment specifying the Psect which is closest to the root segment. 
Therefore, if the Psect MYDATA is specified in the root segment 
and also in one or more overlay segments, the complete allocation 
is placed in the root segment. The OVR attribute tells the Task 
Builder to begin both allocations at the same virtual address. 
Consider Example 2 above. The local symbol M, defined locally in 
the overlay segment, corresponds to the beginning of the Psect in 
the root segment, the address of the first 2. The instruction INC 
M+2 again increments the second 2 to a 3. 


See Appendix E for additional information on how the _ Task 
Builder uses the various Psect attributes. Also see section 3.2.4 
(on Allocation of Program Sections in a Multisegment Task) in the 
RSX-11M/M-PLUS Task Builder Manual for a description of how the 
Task Builder allocates Psects in an overlaid task. 


Two other methods can be used to place in the root a Psect 
which is not defined in the root. If a Psect has the SAV 
attribute, the Task Builder automatically places that Psect's 
allocation in the root. If the Psect does not have the SAV 
attribute, then the .PSECT Overlay Descriptor Language statement 
can be used to specify placement of a particular Psect in the 
root, overriding the default placement. See section 3.4.5 (on the 
-~PSECT Directive) in the RSX-11M/M-PLUS Task Builder Manual for an 
example of the use of .PSECT ODL directive. 


Example 6-6 iS a more complex example of the use of overlays. 
It shows the use of both techniques for placing data in the root 
and referencing it from overlay segments. The program calling 
sequence is shown below. 
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The following notes are keyed to the example. 


The Psect OTHER is set up for uSing overlaid Psects’ to 
reference the data. Since it is defined in the root, the 
entire allocation for OTHER is in the root segment. OPl, 
OP2, and ANS can be just locally defined, since the 
overlay segments define the locations as offsets from the 
Start of the Psect. On the other hand, global symbols can 
be used instead, if desired. The data is an argument 
block for a call to SEDMSG. 


The references to the data from overlay segment JOB1 are 
set up by specifying the Psect OTHER, then defining local 
symbols. .BLKW statements are used because you are just 
defining symbols and offsets. The local symbols NUM1,. 
NUM2, and SUM correspond. to OPl, OP2, and ANS, 
respectively, in MAIN. 


The references to the data from overlay segment JOBXX are 
set up in a similar way. This time the same local symbols 
OP1, OP2, and ANS are used again. 


The references to the data from overlay segment A are also 
set up in ae Similar way. This time only the starting 
address of the argument block is needed. 


The grand total and the ASCII operand (for S$EDMSG) are 
defined with the global symbols TOT and OP. 


The reference to TOT and OP in JOB1l, and JOBXX, are 
automatically resolved directly. No special coding is 
needed in the referencing segment. TOTAL also references 
TOT, this time from the root segment (because TOTAL is 
also in the root segment). 


Note that data which is pure (read-only) and _ referenced 
within the overlay segment only, causes no problems when 
placed in an overlay segment. The references are direct 
and the data is only referenced while the segment is 
loaded. 


The input buffer for the job number typed in by _ the 
operator, and the output buffer for displaying an 
operation's results are contained in an overlay segment 
and changed at run-time. However, Since the data is 
accessed only from within the overlay segment, and only 
while the segment is still loaded, no problems result. 
If, in fact, the MAIN segment referenced this data after a 
call to B was made, it would no longer work correctly 
because on reload, the data is reinitialized. 
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32 ’ Set ur for loor 
53 MOV #39R4 § Counter 
34 LOOF 3 QIOWSC TO.WVBySelvy ys iMES3S»LMES3*40> § Write MESS 
55 CLR ANS i Clear answer in case 
56 > of mo oreration 
57 CALL A ¢ Call subroutine A 
58 SOB R4sLOOF ’ Tecrement counter ana 
59 § loor hack until dane 
460 QTOWSC TO.WVBySotes oe <MES4e9LMES4+»40% ¢ Write MES4 
él CALL TOTAL. § Call routine toa 
62 § disrlay drand total 
63 QIOWSC TO.WVRsSelsyyer<MESS»sLMESS*»40> ¢ Write MESS 
64 EXIT#S § Exit 
65 eEND START 
1 +TITLE A 
2 *IQENT /01/ 
3 *ENABLE LC § Enable lower case 
4 a+ 
3 § FILE A.MAC 
4 ; 
7 § This subroutine diselays 3a messade and then asks which 
8 § of two Jobs to do. It calls the arrrorriate subroutine 
9 § to do the Jioby disrelays the results: and then returns 
10 § to the main Frogram. 
11 jo 
12 *MCALL QTOWSC er QTOWSS § System macros 
13 »+NLIST BEX 5 Tio not list binary 
14 5 extensions 
15 *FSECT OTHER tiyGBLsOVRy REL »RW § FSECT with date 
16 ARG? + BLKW 4 + Set address for start 
17 > of arsument block 
13 »FPSECT § Back to blank FSECT 
19 MES? *ASCII “<112/SEGMENT A IS NOW LOADED. SUBROUTIN/ 
20 *sASCIT /E A IS EXECUTING. 
21 LMES=.~-MES 
2a PMES 3 eASCILI <1127010 YOU WANT TO TO JOR 1 OR JOB 27 / 
23 LEPMES=.~-FMES 
24 EMES? ~ASGCII <152<112/N0 SUCH JOR. SORRY./ 
25 LEMES=.-EMES 


26 OFMT? *ASCIZ 11/20 ZA “2D = ZADLANS 

27 QRUFF » BLAKE 100, Ruffer for disrlay of 
Job results 

Buffer for ineut char 
Move to word houndary 


co 


29 BUFF 3 + BLAKE 1 
30 «EVEN 


“<> “> “S> “Ger 
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26 MES? sASCIT “1ASe2.2><11>/7SEGMENT JOBRI IS NOW LOADED./ 
|» *ASCII “1551 2><11201152/SURROUTINE JOBL IS EX/ 
28 *ASCII /ECUTING./ 
29 LMES=.-MES 
30 + EVEN 
31 »LIST REX ¢ List binary extensions 
32 
33 JOBLII2 QLOWSCO TO.WVBs So leeseiMESyLMES» 40> ¢ Disrlay 
34 § mMessade 
@ 3S MOV NUM1» SUM y First orerand to ans 
34 Ant NUM2 » SUM ys Adc in other orerand 
re] 37 Alt SUM» TOT ¢ Add this answer to total 
38 MOV #/+90F > Move orerand for outeut 
39 § disrlay 
40 RETURN > Return 
41 +ENT 
1 *+TITLE JOBXX 
2 +IQENT /017 
3 *ENABRL LC y Enable lower case 
4 i+ 
wo y FILE JORXX.MAC 
& ; 
ze y This subroutine rerforms @ multielication oreration. 
8 $ It is assumed that local symbols OF 1s OF2 and ANS 
9 y corresrond to the same local symbols im MAIN. The 
10 * Slobal symbol TOTs defined in MAIN» is the address 
li s where the drand total is maintained. 
12 p~ 
13 eMCALL QTOWSC y External s¥stem macros 
14 eNLIST BEX § flo not list binary 
18 § extensions 
16 »+FSECT OTHER DUvGRLsOVReREL es RW ¢ Date FPSECT 
17 OF? +BLAW 1: § ist orerand 
3) 18 »BLAW 1 § Address of oreration 
i? § ain ASCII 
20 OF? 3 + BLIW 1 § 2nd orerand 
2 ANS? +BLKW 1 % Answer 
or) 
23 +PSECT 3’ Kack to blank FSECT 
24 +BLKW 1024.2 } Leave srace to make 
2 § module larger 
— | 26 MES? *ASCIT 152112112 /SEGMENT JOBXX IS NOW? 
o| » *ASCITI / LOANEN, /*£1 S21 222112<11> 
28 *ASCII /SUBROUTINE JOB2 IS EXECUTING./ 
29 LMES=.-MES 
30 +EVEN 


31 +LISt REX § List binary extensions 
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»TITLE & 
+IQENT /01/7 ; 
*+ENABL LC § Enable lower case 
a+ 
§ FILE BeMAC 
r 
i This subroutine disrlays @ messede and returns 
37 
*+MCALL QTOWsC s External system macros 
»NLIST BEX * tio not list binary 
+ extensions 
MES? *ASCITI “<112/SEGMENT B&B IS NOW LOADED. SUBROUTINES 
*ASCII / &B IS EXECUTING./ 
LMES = . ~- MES 
eEVEN + Move to word boundary 
3 
Bit QIOWSC TO WVBR Soleo vsetMESsLMES»40> ¢ Diselay 
5 mMessade 
RETURN + Return 
ENT 


Session 


“RUN MRMAIN 


THE 


THE 


THE 


THE 


THE 


THE 
THE 


THE: 


MAIN SEGMENT IS RUNNING ANID WILL CALL A | 
SEGMENT A IS NOW LOADED, SUBROUTINE A IS EXECUTING. 
DO YOU WANT TO DO JOB 1 OR JOR 2? 1 
SEGMENT JOR1 IS NOW LOADED. 
SUBROUTINE JOBR1 IS EXECUTING. 
S+2= 7 


MAIN SEGMENT WILL NOW CALL B 
SEGMENT B IS NOW LOADED. SUBROUTINE B IS EXECUTING. 
MAIN SEGMENT WILL NOW CALL A 
SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING. 
lO YOU WANT TO DO JOR 1 OR JOB 2? 2 
SEGMENT JORXX IS NOW LOADED, 
SUBROUTINE JOBR2 IS EXECUTING. 
7 XK 2 = 10 


MAIN SEGMENT WILL NOW CALL A 
SEGMENT A TS NOW LOANED, SUBROUTINE A IS EXECUTING. 
nO YOU WANT TO NO JOB 1 OR JOR 2? 2 
SEGMENT JORXX IS NOW LOANED. 
SUBROUTINE JOB2 IS EXECUTING. 
2k 2 = 10 


MAIN SEGMENT WILL NOW CALL A 
SEGMENT A IS NOW LOADED, SUBROUTINE A IS EXECUTING. 
NO YOU WANT TO TO JOB 1 OR JOB 2? 1 
SEGMENT JOB1 IS NOW LOADED. 
SUBROUTINE JOBL IS EXECUTING. 
o +2 = 7 


MAIN SEGMENT WILL CALL TOTAL 
GRAND TOTAL IS 34, 


MAIN SEGMENT WILL NOW EXIT 
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Al A2 B1 B2 
AO BO 
Y 
| 
fl 
CNTRL 


TK-8635 


Figure 6-7 Task Without Co-Trees 
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Now do the tests/exercises’ for this module in the 
Tests/Exercises book. All but the first problem are lab problems. 
Check your answers against the provided solutions, either’ the 
on-line files (under UFD [2@2,2] or the printed copies in the 
Tests/Exercises book. 


If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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